468 lines
15 KiB
Markdown
468 lines
15 KiB
Markdown
# 同行者可见即可说自动注册框架对接方案 - 快速阅读版
|
||
|
||
> 来源文档：`F:/AI/Obsidian/项目文档/徐工/语音/同行者可见即可说自动注册框架对接方案.docx`
|
||
> 整理日期：2026-06-13
|
||
> 目标：把原 Word 文档整理成工程接入时能快速查阅的 Markdown 速查文档。
|
||
|
||
## 1. 一句话结论
|
||
|
||
“可见即可说”主要依赖 Android 无障碍服务扫描当前界面控件，通过控件的 `android:id`、`android:text`、`android:contentDescription`、`clickable`、`scrollable` 等信息自动注册语音热词。用户说出界面上可见或已通过隐藏标签声明的词后，语音助手命中热词，再回调触发目标控件事件。
|
||
|
||
如果界面元素无法被无障碍扫描，例如小程序、网页、自绘界面，则需要应用主动通过 AIDL 或广播向语音发送插词列表，语音命中后再把命中的插词回传给应用，由应用自行执行动作。
|
||
|
||
## 2. 整体链路
|
||
|
||
### 2.1 普通 Android 控件链路
|
||
|
||
1. 应用界面展示控件。
|
||
2. Android 无障碍服务扫描界面控件。
|
||
3. 语音助手读取控件文本或隐藏标签。
|
||
4. 语音助手把文本注册为可见即可说热词。
|
||
5. 用户说出对应词，例如“每日推荐”或“打开每日推荐”。
|
||
6. 热词模块命中控件节点。
|
||
7. 无障碍服务触发控件点击或滑动等事件。
|
||
8. 应用执行原控件逻辑。
|
||
|
||
### 2.2 图标控件链路
|
||
|
||
图标本身不显示文字时，需要通过 `contentDescription` 提供隐藏标签。例如图标按钮没有文字，但设置了 `android:contentDescription="向下滑"`，语音仍可识别“向下滑”并触发该图标。
|
||
|
||
### 2.3 非常规界面链路
|
||
|
||
适用于小程序、网页、自绘页面等无障碍拿不到元素的场景。
|
||
|
||
1. 应用整理当前界面可执行插词列表。
|
||
2. 应用通过 AIDL 或广播发送给语音。
|
||
3. 语音收到后注册插词。
|
||
4. 用户说出插词。
|
||
5. 语音识别命中。
|
||
6. 语音通过 AIDL 或广播把命中插词回传给应用。
|
||
7. 应用根据插词匹配具体控件或业务动作。
|
||
|
||
## 3. 接入总原则
|
||
|
||
| 原则 | 说明 |
|
||
|---|---|
|
||
| 必须有唯一 ID | 所有需要语音响应的控件都应设置唯一 `android:id`。 |
|
||
| 文本优先 | 文本控件优先使用 `android:text` 暴露插词。 |
|
||
| 图标补标签 | 图标类控件使用 `android:contentDescription` 暴露隐藏插词。 |
|
||
| 多说法用 `#` | 多个插词使用 `#` 分隔，例如 `打开#启动`。 |
|
||
| 状态要同步 | 播放/暂停、收藏/取消收藏等状态型图标必须动态更新 `contentDescription`。 |
|
||
| 点击看 `clickable` | 控件是否响应与 `clickable` 状态有关，`true` 表示可点击。 |
|
||
| 滚动看 `scrollable` | 滑动控件本身需要是可滑动节点，即 `Scrollable=true`。 |
|
||
| 弹窗用标准 Dialog | 建议使用标准 `Dialog` 或依附 Activity 的自定义 Dialog。 |
|
||
|
||
## 4. 常见控件接入方式
|
||
|
||
## 4.1 文本类控件
|
||
|
||
适用对象：`TextView`、`Button`、带文本的布局项等。
|
||
|
||
推荐做法：
|
||
|
||
```xml
|
||
<TextView
|
||
android:id="@+id/tv_daily_recommend"
|
||
android:layout_width="wrap_content"
|
||
android:layout_height="wrap_content"
|
||
android:clickable="true"
|
||
android:text="每日推荐" />
|
||
```
|
||
|
||
支持泛化说法时，可使用 `contentDescription`：
|
||
|
||
```xml
|
||
<TextView
|
||
android:id="@+id/tv_daily_recommend"
|
||
android:layout_width="wrap_content"
|
||
android:layout_height="wrap_content"
|
||
android:clickable="true"
|
||
android:text="每日推荐"
|
||
android:contentDescription="每日推荐#打开每日推荐#我想打开每日推荐" />
|
||
```
|
||
|
||
注意：
|
||
|
||
- `contentDescription` 中的插词文本必须包含 `text` 中的文本。
|
||
- 控件要能响应点击，需确保 `clickable=true` 或实际可点击。
|
||
|
||
## 4.2 图标类控件
|
||
|
||
适用对象：只有图片、没有文本的按钮或图标。
|
||
|
||
```xml
|
||
<ImageView
|
||
android:id="@+id/iv_search"
|
||
android:layout_width="wrap_content"
|
||
android:layout_height="wrap_content"
|
||
android:clickable="true"
|
||
android:contentDescription="搜索#查找" />
|
||
```
|
||
|
||
注意：
|
||
|
||
- 图标没有显示文本时，必须用 `contentDescription` 提供语音插词。
|
||
- 多个插词用 `#` 分隔。
|
||
- 控件是否响应仍与 `clickable` 状态有关。
|
||
|
||
## 4.3 同一图标多状态控件
|
||
|
||
典型场景：播放/暂停、收藏/取消收藏。
|
||
|
||
错误做法：
|
||
|
||
```xml
|
||
android:contentDescription="播放#暂停"
|
||
```
|
||
|
||
这种做法可能导致当前处于暂停状态时，用户说“暂停”反而触发点击，结果开始播放。
|
||
|
||
正确做法：根据状态动态更新。
|
||
|
||
```java
|
||
if (isPlaying) {
|
||
playButton.setContentDescription("暂停");
|
||
} else {
|
||
playButton.setContentDescription("播放");
|
||
}
|
||
```
|
||
|
||
原则：
|
||
|
||
- 当前正在播放，插词应是“暂停”。
|
||
- 当前已经暂停，插词应是“播放”。
|
||
- 当前已收藏，插词应是“取消收藏”。
|
||
- 当前未收藏，插词应是“收藏”。
|
||
|
||
## 4.4 常规滑动控件
|
||
|
||
适用对象：`ScrollView`、`RecyclerView`、`ListView` 等。
|
||
|
||
基础要求：
|
||
|
||
- 控件本身应可滑动，即无障碍节点 `Scrollable=true`。
|
||
- 如果每个 item 需要响应语音，item 需要有唯一 ID。
|
||
- item 可使用 `contentDescription` 声明插词。
|
||
- 如需响应 item 内部 child 控件，child 按文本类或图标类控件处理。
|
||
|
||
示例：
|
||
|
||
```xml
|
||
<RecyclerView
|
||
android:id="@+id/rv_station_list"
|
||
android:layout_width="match_parent"
|
||
android:layout_height="match_parent" />
|
||
```
|
||
|
||
item 示例：
|
||
|
||
```xml
|
||
<TextView
|
||
android:id="@+id/tv_station_name"
|
||
android:layout_width="wrap_content"
|
||
android:layout_height="wrap_content"
|
||
android:clickable="true"
|
||
android:text="88.6MHz"
|
||
android:contentDescription="88.6MHz#播放88.6" />
|
||
```
|
||
|
||
## 4.5 翻页控制
|
||
|
||
文档中特别强调：如果要让可见即可说支持“上一页 / 下一页”这类翻页逻辑，应用需要预留两个大小为 0 的控件。
|
||
|
||
要求：
|
||
|
||
- 控件大小为 0。
|
||
- 不能设置为 `GONE`。
|
||
- 分别添加“上一页”“下一页”等 `contentDescription`。
|
||
- 应用自己实现点击事件，点击后控制对应滚动控件翻页。
|
||
- 如果页面中有多个同方向滚动控件，只建议配置用户最可能使用的那个。
|
||
- 多组 0 大小翻页控件可能导致目标滚动控件不符合预期。
|
||
|
||
示例：
|
||
|
||
```xml
|
||
<View
|
||
android:id="@+id/voice_page_prev"
|
||
android:layout_width="0dp"
|
||
android:layout_height="0dp"
|
||
android:clickable="true"
|
||
android:contentDescription="上一页" />
|
||
|
||
<View
|
||
android:id="@+id/voice_page_next"
|
||
android:layout_width="0dp"
|
||
android:layout_height="0dp"
|
||
android:clickable="true"
|
||
android:contentDescription="下一页" />
|
||
```
|
||
|
||
```java
|
||
voicePagePrev.setOnClickListener(v -> recyclerView.smoothScrollBy(0, -recyclerView.getHeight()));
|
||
voicePageNext.setOnClickListener(v -> recyclerView.smoothScrollBy(0, recyclerView.getHeight()));
|
||
```
|
||
|
||
如果不预留翻页控制控件，默认不支持翻页逻辑。
|
||
|
||
## 4.6 SeekBar 等特殊滑动控件
|
||
|
||
适用对象：亮度、音量、进度条等 `SeekBar` 控件。
|
||
|
||
接入目标：支持类似“调高屏幕亮度”“降低音量”“屏幕亮度调大一点”等语音指令。
|
||
|
||
推荐做法：
|
||
|
||
```xml
|
||
<SeekBar
|
||
android:id="@+id/sb_screen_brightness"
|
||
android:layout_width="match_parent"
|
||
android:layout_height="wrap_content"
|
||
android:paddingStart="0dp"
|
||
android:paddingEnd="0dp"
|
||
android:contentDescription="屏幕亮度" />
|
||
```
|
||
|
||
父布局建议：
|
||
|
||
```xml
|
||
android:clipChildren="false"
|
||
android:clipToPadding="false"
|
||
```
|
||
|
||
原因：
|
||
|
||
- 框架根据控件宽高计算百分比拖动距离。
|
||
- 无法直接读取控件内部业务值。
|
||
- `SeekBar` 默认内边距会造成拖动精度误差。
|
||
- 将 `SeekBar` 内边距设为 0，并允许子控件超出父布局边界，可减少误差。
|
||
|
||
## 4.7 Switch 开关类控件
|
||
|
||
原生 `Switch`：通常无需额外适配。
|
||
|
||
自定义开关 View：需要重写 `onInitializeAccessibilityNodeInfo`。
|
||
|
||
```java
|
||
@Override
|
||
public void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) {
|
||
super.onInitializeAccessibilityNodeInfo(info);
|
||
info.setCheckable(true);
|
||
info.setChecked(isChecked());
|
||
}
|
||
```
|
||
|
||
要求：
|
||
|
||
- 设置 `checkable=true`。
|
||
- 根据真实开关状态同步 `checked`。
|
||
- 状态变化时及时刷新无障碍信息。
|
||
|
||
## 5. 非常规界面 AIDL / 广播对接字段
|
||
|
||
文档流程图给出的字段含义如下。
|
||
|
||
## 5.1 应用发送给语音：注册或取消注册
|
||
|
||
| 字段 | 含义 | 示例 |
|
||
| ------------- | --------------------- | ------------------------------------------------------ |
|
||
| `key_type` | 要处理的类型，`2600` 表示可见即可说 | `2600` |
|
||
| `action` | 动作 | `shadow.register` / `shadow.unregister` |
|
||
| `packageName` | 应用包名，可不填 | `com.yaxon.carcontrol` |
|
||
| `className` | 页面类名，可不填 | `com.yaxon.carcontrol.activity.CarControlMainActivity` |
|
||
| `pageName` | 页面名称，可不填 | `voiceSetting` |
|
||
| `keywordList` | 插词列表，泛化词用 `#` 分隔 | `打开#启动` |
|
||
|
||
示例：
|
||
|
||
```json
|
||
{
|
||
"key_type": 2600,
|
||
"action": "shadow.register",
|
||
"packageName": "com.yaxon.carcontrol",
|
||
"className": "com.yaxon.carcontrol.activity.CarControlMainActivity",
|
||
"pageName": "voiceSetting",
|
||
"keywordList": "打开#启动"
|
||
}
|
||
```
|
||
|
||
取消注册：
|
||
|
||
```json
|
||
{
|
||
"key_type": 2600,
|
||
"action": "shadow.unregister",
|
||
"packageName": "com.yaxon.carcontrol",
|
||
"pageName": "voiceSetting",
|
||
"keywordList": "打开#启动"
|
||
}
|
||
```
|
||
|
||
## 5.2 语音回传给应用：命中执行
|
||
|
||
| 字段 | 含义 | 示例 |
|
||
| ---------- | --------------------- | ---------------- |
|
||
| `key_type` | 回传类型，`1600` 表示可见即可说执行 | `1600` |
|
||
| `action` | 动作 | `shadow.execute` |
|
||
| `cmd` | 命中的插词原文 | `打开` |
|
||
|
||
示例：
|
||
|
||
```json
|
||
{
|
||
"key_type": 1600,
|
||
"action": "shadow.execute",
|
||
"cmd": "打开"
|
||
}
|
||
```
|
||
|
||
应用收到后，应根据 `cmd` 做业务分发。
|
||
|
||
## 6. 已知问题与规避方式
|
||
|
||
## 6.1 `com.android.systemui` 扫描冲突
|
||
|
||
问题：
|
||
|
||
- 底部 touch 栏中可能存在很多图标插词。
|
||
- 这些插词可能和桌面或其他应用重复，例如“车主手册”。
|
||
- `com.android.systemui` 所在 window 可能一直可见，即使视觉上隐藏，也可能被无障碍服务扫描到。
|
||
- 用户说“车主手册”时，可能命中 SystemUI 上隐藏的控件，导致结果不符合预期。
|
||
|
||
建议：
|
||
|
||
- SystemUI 隐藏时，临时清空相关控件的 `android:text` 和 `android:contentDescription`。
|
||
- SystemUI 重新显示时，再恢复文本和隐藏标签。
|
||
|
||
示例：
|
||
|
||
```java
|
||
if (isSystemUiHidden) {
|
||
view.setContentDescription(null);
|
||
textView.setText("");
|
||
} else {
|
||
view.setContentDescription("车主手册");
|
||
textView.setText("车主手册");
|
||
}
|
||
```
|
||
|
||
## 6.2 同一图片不同插词
|
||
|
||
问题：
|
||
|
||
- 同一图片可能对应不同状态，例如播放/暂停。
|
||
- 如果同时注册“播放#暂停”，当前状态下可能执行反向动作。
|
||
|
||
建议：
|
||
|
||
- 状态变化时动态更新 `contentDescription`。
|
||
- 当前能执行什么动作，就只暴露什么插词。
|
||
|
||
## 6.3 部分弹框扫描不到
|
||
|
||
问题：
|
||
|
||
- 一些通过 Window 直接创建的弹框，可能与 Activity 界面不匹配或层级冲突。
|
||
- 无障碍服务可能扫描不到弹框里的控件。
|
||
|
||
建议：
|
||
|
||
- 优先使用标准 `Dialog`。
|
||
- 自定义 Dialog 应依附于 Activity。
|
||
- 避免直接用独立 Window 承载需要语音响应的弹框。
|
||
|
||
## 7. 工程接入检查清单
|
||
|
||
## 7.1 页面级检查
|
||
|
||
- [ ] 页面中需要语音响应的控件是否都有唯一 `android:id`。
|
||
- [ ] 文本控件是否有明确 `android:text`。
|
||
- [ ] 图标控件是否设置了 `android:contentDescription`。
|
||
- [ ] 多说法是否使用 `#` 分隔。
|
||
- [ ] 控件是否实际可点击或可滑动。
|
||
- [ ] 动态状态控件是否会更新 `contentDescription`。
|
||
- [ ] 列表 item 是否有唯一 ID 或稳定的可识别标签。
|
||
- [ ] 滚动页面是否需要预留上一页/下一页控制控件。
|
||
- [ ] 弹框是否使用标准 Dialog 或依附 Activity。
|
||
|
||
## 7.2 状态型控件检查
|
||
|
||
- [ ] 播放状态：播放中只暴露“暂停”。
|
||
- [ ] 暂停状态：暂停中只暴露“播放”。
|
||
- [ ] 已收藏：只暴露“取消收藏”。
|
||
- [ ] 未收藏：只暴露“收藏”。
|
||
- [ ] 开关类自定义 View 是否正确设置 `checkable` 和 `checked`。
|
||
|
||
## 7.3 SystemUI 检查
|
||
|
||
- [ ] 隐藏状态是否仍可能被无障碍扫描。
|
||
- [ ] 隐藏时是否清空 `text/contentDescription`。
|
||
- [ ] 显示时是否恢复 `text/contentDescription`。
|
||
- [ ] 是否存在与 Launcher 或 App 页面重复的插词。
|
||
|
||
## 7.4 非常规界面检查
|
||
|
||
- [ ] 是否确认无障碍无法获取页面元素。
|
||
- [ ] 是否整理了当前页面插词列表。
|
||
- [ ] 是否支持注册和取消注册。
|
||
- [ ] 是否能接收语音命中的 `cmd`。
|
||
- [ ] `cmd` 到业务动作是否有明确映射表。
|
||
- [ ] 页面销毁或切换时是否取消旧插词。
|
||
|
||
## 8. 当前徐工项目建议落地顺序
|
||
|
||
1. 先验证 `YX_Voice` 与同行者之间的 `shadow.register` / `shadow.execute` 链路。
|
||
2. 在 `YX_CarControl` 做一个测试插词，不绑定真实业务动作，只看日志是否能完整闭环。
|
||
3. 链路确认后，再选一个真实页面做最小闭环，例如语音设置页或声音设置页。
|
||
4. 对原生 Android 控件，优先走无障碍自动扫描，不额外走 AIDL/广播。
|
||
5. 对自绘、网页、小程序、复杂浮窗，走 AIDL/广播注册插词。
|
||
6. 对 SystemUI、Launcher、Music、Radio 这类插词多且易冲突的模块，先做页面级插词清单，再逐个治理冲突。
|
||
|
||
## 9. 日志验证建议
|
||
|
||
注册阶段重点看：
|
||
|
||
```text
|
||
registerVisibleSpeakKeywords
|
||
shadow.register
|
||
keywordList
|
||
```
|
||
|
||
命中阶段重点看：
|
||
|
||
```text
|
||
shadow.execute
|
||
cmd
|
||
handleVisibleSpeakExecute
|
||
```
|
||
|
||
异常排查重点看：
|
||
|
||
```text
|
||
keywordList is empty
|
||
TXZ not connected
|
||
protocolLogic is null
|
||
packageName or cmd is empty
|
||
```
|
||
|
||
## 10. 快速判断表
|
||
|
||
| 现象 | 优先排查 |
|
||
| ------------ | --------------------------------------------- |
|
||
| 说了没反应 | 控件是否有 ID、是否 clickable、是否注册成功 |
|
||
| 图标不能说 | 是否设置 `contentDescription` |
|
||
| 状态动作反了 | 是否动态更新 `contentDescription` |
|
||
| 列表不能翻页 | 是否预留 0 大小上一页/下一页控件 |
|
||
| SeekBar 拖动不准 | 是否去掉 SeekBar 内边距，父布局是否设置 `clipChildren=false` |
|
||
| 弹框扫不到 | 是否用标准 Dialog 或依附 Activity |
|
||
| 命中到错误应用 | 是否存在 SystemUI / Launcher / 当前页面插词冲突 |
|
||
| 非常规页面无元素 | 改走 AIDL 或广播插词注册 |
|
||
|
||
## 11. 后续需求明确后需要补充的内容
|
||
|
||
- 每个模块的可见即可说页面清单。
|
||
- 每个页面的控件 ID、显示文本、隐藏标签、状态规则。
|
||
- 插词冲突表，尤其是 SystemUI、Launcher、CarControl、Music、Radio。
|
||
- 非常规界面的 AIDL / 广播接口定义。
|
||
- 命中 `cmd` 到实际业务动作的映射表。
|
||
- 现场日志验证结果。
|