更新记录

1.0.1（2026-05-10） 下载此版本

重构

1.0.0（2025-08-28） 下载此版本

经过 华为、荣耀、小米、oppo、vivo 真机测试，正常运行。需开发人员根据业务自己适配具体功能。

平台兼容性

uni-app(5.08)

uni-app x(5.08)

laoqianjunzi-accessi

平台支持

• Android App：支持完整能力
• Web：空实现，仅用于编译兜底
• iOS：空实现，仅用于编译兜底
• Harmony：空实现，仅用于编译兜底

导入方式

在页面或公共 .uts 文件中统一从插件根目录导入：

import {
    openAccessibilitySettings,
    isAccessibilitySettingsOn,
    findNodes,
    performClickAt
} from '@/uni_modules/laoqianjunzi-accessi'

推荐使用流程

建议按下面的顺序调用：

1. 先用 isAccessibilitySettingsOn() 或 isAccessibilityEnabled() 判断服务状态
2. 未开启时调用 openAccessibilitySettings() 引导用户开启
3. 再根据业务场景选择全局操作、节点操作、监听能力或手势能力
4. 如果使用事件监听，页面销毁时记得调用 stopListener()
5. 如果要做复杂授权或设置页自动化，优先使用 readRomProfile()、recognizeSettingsPage() 与 runAutomationFlow() 组合

能力分层

插件目前建议按三层理解：

• 基础层：服务状态、系统级动作、节点查找、手势操作
• 结构化层：AccessLocator、collectMatches()、executeOnMatch()、exportNodeTree()
• 编排层：AccessFlowStep、runAutomationFlow()、getAutomationFlowState()、stopAutomationFlow()

API 分类

1. 服务状态与设置

示例：

const enabled = isAccessibilitySettingsOn()
if (!enabled) {
    openAccessibilitySettings()
}

2. 应用调度与全局操作

示例：

launchApp('com.android.settings')
performBackAction()
performHomeAction()

3. 快捷节点操作

说明：

• type 取值为 'text' 或 'id'
• identifier 为节点文本或节点 id

示例：

const found = findNodeByText('允许')
if (found) {
    clickNodeByText('允许')
}

const checked = getCheckState('允许通知')
if (checked == false) {
    setCheckState('允许通知', true)
}

4. 事件监听

回调数据格式：

• 第 1 项：类名
• 第 2 项：包名
• 第 3 项：事件类型

示例：

startListener(['com.android.settings'], true, (eventData : Array<string>) => {
    console.log('eventData', eventData)
})

stopListener()

5. 节点判断与批量检查

常见过滤字段：

• viewId
• text
• contentDesc
• className
• packageName
• hint
• visible
• enabled
• clickable
• focusable
• focused
• textMatch
• contentDescMatch
• hintMatch

示例：

const exists = checkNodeByViewIdAndTextAndContentDesc({
    text: '确定'
})

const count = getNodesCount({
    text: '确定',
    clickable: true
})

6. 高级节点操作

operateNodeAdvanced(options) 重点参数：

• index: 节点索引数组，如 [0]
• actionType: click、doubleclick、longclick、focus、scroll_forward、scroll_backward 等
• edit: 要输入的文本；传空字符串可清空输入框
• 其它筛选字段与 getNodesCount 基本一致

示例：

inputTextToNode({
    hint: '请输入手机号',
    index: [0],
    inputText: '***'
})

clickNodeIndex({
    text: '登录',
    index: 0
})

7. 节点详情与环境信息

示例：

const nodes = findNodes({
    text: '允许',
    clickable: true
})

const screenSize = getScreenSize()
console.log('width', screenSize.get('width'))
console.log('height', screenSize.get('height'))

8. 手势模拟

示例：

performSwipeUp(500, 800, 400)
performClickAt(540, 1200, 100)
performClickAtRelative(0.5, 0.5)

9. 结构化能力与流程编排

新增一组更适合复杂自动化的能力：

• readBridgeState()：读取插件桥接状态
• readRomProfile() / recognizeSettingsPage() / matchSettingsPage()：读取 ROM 指纹并识别当前设置页
• beginEventFeed() / finishEventFeed()：结构化事件订阅
• exportNodeTree() / collectMatches()：输出树形节点快照、批量命中结果
• inspectTarget() / inspectBatch() / measureMatches()：条件判断与匹配计数
• executeOnMatch() / tapMatch() / fillMatch()：按结构化定位条件执行动作
• runAutomationFlow() / getAutomationFlowState() / stopAutomationFlow()：内置轻量流程执行器，支持步骤、等待、重试、延迟、失败继续

结构化 locator 常用字段：

• text / textMatch
• contentDesc / contentDescMatch
• viewId
• className
• packageName
• clickable / enabled / visible

结构化执行示例：

const exists = inspectTarget({
    text: '允许',
    clickable: true
} as UTSJSONObject)

if (exists) {
    tapMatch({
        text: '允许',
        clickable: true
    } as UTSJSONObject)
}

流程步骤常见动作：

• launch_app
• wait
• wait_match
• tap
• tap_point
• input
• toggle
• back
• home
• close_settings

示例：

import {
    getAutomationFlowState,
    runAutomationFlow,
    stopAutomationFlow
} from '@/uni_modules/laoqianjunzi-accessi'

const started = runAutomationFlow([
    {
        stepId: 'open-settings',
        action: 'launch_app',
        targetPackage: 'com.android.settings',
        delayAfter: 1200
    },
    {
        stepId: 'wait-notification',
        action: 'wait_match',
        locator: {
            text: '通知'
        } as UTSJSONObject,
        waitTimeout: 5000,
        waitInterval: 300
    },
    {
        stepId: 'tap-notification',
        action: 'tap',
        locator: {
            text: '通知'
        } as UTSJSONObject,
            retryCount: 2,
            retryInterval: 500,
            retryAction: 'scroll_forward'
    }
])

if (!started) {
    console.log('流程未启动', getAutomationFlowState())
}

// 页面销毁或用户手动终止时
stopAutomationFlow()

10. ROM 与设置页识别

这组能力适合权限引导、品牌差异分流、自启动/悬浮窗/使用情况访问等系统设置自动化。

内置已覆盖的页面 key 包括：

• system_settings
• accessibility
• overlay_permission
• usage_access
• notification_manager
• autostart_manager
• battery_manager
• app_manager

示例：

const profile = readRomProfile()
console.log('vendor', profile.vendor)

const page = recognizeSettingsPage()
if (page != null) {
    console.log('当前设置页', page.pageKey, page.matchedKeywords)
}

if (matchSettingsPage('autostart_manager')) {
    console.log('当前已经进入自启动管理页')
}

常见组合示例

示例 1：检查服务并引导开启

if (!isAccessibilitySettingsOn()) {
    openAccessibilitySettings()
}

示例 2：等待按钮出现后点击

const exists = checkNodeByViewIdAndTextAndContentDesc({
    text: '同意并继续'
})

if (exists) {
    clickNodeByText('同意并继续')
}

示例 3：监听指定应用事件

startListener(['com.tencent.mm'], true, (data : Array<string>) => {
    console.log('监听到事件', data)
})

示例 4：按 ROM 分流授权逻辑

const profile = readRomProfile()

if (profile.vendor == 'xiaomi') {
    console.log('走小米权限路径')
} else if (profile.vendor == 'vivo') {
    console.log('走 vivo 权限路径')
} else {
    console.log('走通用权限路径')
}

注意事项

• 本插件主要面向 Android App，真机能力依赖无障碍服务授权
• openAccessibilitySettings() 只能拉起设置页，用户仍需手动开启服务
• 节点匹配依赖目标应用当前页面结构，系统升级或应用改版后可能需要调整参数
• 使用监听能力后请及时调用 stopListener()，避免页面退出后仍持续回调
• runAutomationFlow() 当前是轻量执行器，适合设置页授权、确定性流程，不建议直接替代复杂业务状态机
• recognizeSettingsPage() 是启发式识别，适合做分流和容错，不建议把单一关键词识别当成唯一判断条件
• 非 Android 平台只有空实现，返回值通常为 false、0、null 或空集合