在 TV 应用中支持 TalkBack
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
TV 应用的用例有时会使依赖
TalkBack 即可使用应用。为了给这些应用提供更好的 TalkBack 体验
请阅读本指南的各个部分,
。如果您的应用使用自定义视图,您还应参考
相应指南,其中介绍了如何通过自定义
观看次数。
处理嵌套视图
TalkBack 用户很难通过嵌套视图来浏览内容。请尽可能确保
父视图或子视图可由 TalkBack 聚焦,但不能同时设置为两者。
如需使某个视图可被 TalkBack 聚焦,请设置 focusable
和
focusableInTouchMode
属性设为 true
。此步骤必不可少,因为
当 TalkBack 处于启用状态时,某些电视设备可能会进入和退出触摸模式。
如需使视图不可聚焦,只需设置 focusable
属性设为 false
。不过,如果该视图可操作(即
相应的 AccessibilityNodeInfo
具有 ACTION_CLICK
),它可能仍然
具有可聚焦性。
操作的变更说明
默认情况下,TalkBack 会读出“按选择即可激活”获取可作为行动依据的视图
对于某些操作,系统会显示“启用”一词说明可能不太合适。接收者
提供更准确的说明,您可以按以下步骤进行更改:
Kotlin
findViewById<View>(R.id.custom_actionable_view).accessibilityDelegate = object : View.AccessibilityDelegate() {
override fun onInitializeAccessibilityNodeInfo(host: View, info: AccessibilityNodeInfo) {
super.onInitializeAccessibilityNodeInfo(host, info)
info.addAction(
AccessibilityAction(
AccessibilityAction.ACTION_CLICK.id,
getString(R.string.custom_label)
)
)
}
}
Java
findViewById(R.id.custom_actionable_view).setAccessibilityDelegate(new AccessibilityDelegate() {
@Override
public void onInitializeAccessibilityNodeInfo(View host, AccessibilityNodeInfo info) {
super.onInitializeAccessibilityNodeInfo(host, info);
AccessibilityAction action = new AccessibilityAction(
AccessibilityAction.ACTION_CLICK.getId(), getString(R.string.custom_label));
info.addAction(action);
}
});
添加对滑块的支持
电视上的 TalkBack 对滑块提供特殊支持。要启用滑块模式,请将
将 ACTION_SET_PROGRESS
与 RangeInfo
对象一起添加到视图。
用户通过按电视遥控器的中心按钮进入滑块模式。
在此模式下,箭头按钮会生成 ACTION_SCROLL_FORWARD
和
ACTION_SCROLL_BACKWARD
无障碍操作。
以下示例会实现级别为 1 到 10 的音量滑块:
Kotlin
/**
* This example only provides slider functionality for TalkBack users. Additional logic should
* be added for other users. Such logic may reuse the increase and decrease methods.
*/
class VolumeSlider(context: Context?, attrs: AttributeSet?) : LinearLayout(context, attrs) {
private val min = 1
private val max = 10
private var current = 5
private var textView: TextView? = null
init {
isFocusable = true
isFocusableInTouchMode = true
val rangeInfo =
AccessibilityNodeInfo.RangeInfo(
AccessibilityNodeInfo.RangeInfo.RANGE_TYPE_INT,
min.toFloat(),
max.toFloat(),
current.toFloat()
)
accessibilityDelegate =
object : AccessibilityDelegate() {
override fun onInitializeAccessibilityNodeInfo(host: View, info: AccessibilityNodeInfo) {
super.onInitializeAccessibilityNodeInfo(host, info)
info.addAction(AccessibilityNodeInfo.AccessibilityAction.ACTION_SET_PROGRESS)
info.rangeInfo = rangeInfo
}
override fun performAccessibilityAction(host: View, action: Int, args: Bundle?): Boolean {
if (action == AccessibilityNodeInfo.AccessibilityAction.ACTION_SCROLL_FORWARD.id) {
increase()
return true
}
if (action == AccessibilityNodeInfo.AccessibilityAction.ACTION_SCROLL_BACKWARD.id) {
decrease()
return true
}
return super.performAccessibilityAction(host, action, args)
}
}
}
override fun onFinishInflate() {
super.onFinishInflate()
textView = findViewById(R.id.text)
textView!!.text = context.getString(R.string.level, current)
}
private fun increase() {
update((current + 1).coerceAtMost(max))
}
private fun decrease() {
update((current - 1).coerceAtLeast(min))
}
private fun update(newLevel: Int) {
if (textView == null) {
return
}
val newText = context.getString(R.string.level, newLevel)
// Update the user interface with the new volume.
textView!!.text = newText
// Announce the new volume.
announceForAccessibility(newText)
current = newLevel
}
}
Java
/**
* This example only provides slider functionality for TalkBack users. Additional logic should
* be added for other users. Such logic can reuse the increase and decrease methods.
*/
public class VolumeSlider extends LinearLayout {
private final int min = 1;
private final int max = 10;
private int current = 5;
private TextView textView;
public VolumeSlider(Context context, AttributeSet attrs) {
super(context, attrs);
setFocusable(true);
setFocusableInTouchMode(true);
RangeInfo rangeInfo = new RangeInfo(RangeInfo.RANGE_TYPE_INT, min, max, current);
setAccessibilityDelegate(
new AccessibilityDelegate() {
@Override
public void onInitializeAccessibilityNodeInfo(View host, AccessibilityNodeInfo info) {
super.onInitializeAccessibilityNodeInfo(host, info);
info.addAction(AccessibilityAction.ACTION_SET_PROGRESS);
info.setRangeInfo(rangeInfo);
}
@Override
public boolean performAccessibilityAction(View host, int action, Bundle args) {
if (action == AccessibilityAction.ACTION_SCROLL_FORWARD.getId()) {
increase();
return true;
}
if (action == AccessibilityAction.ACTION_SCROLL_BACKWARD.getId()) {
decrease();
return true;
}
return super.performAccessibilityAction(host, action, args);
}
});
}
@Override
protected void onFinishInflate() {
super.onFinishInflate();
textView = findViewById(R.id.text);
textView.setText(getContext().getString(R.string.level, current));
}
private void increase() {
update(Math.min(current + 1, max));
}
private void decrease() {
update(Math.max(current - 1, min));
}
private void update(int newLevel) {
if (textView == null) {
return;
}
String newText = getContext().getString(R.string.level, newLevel);
// Update the user interface with the new volume.
textView.setText(newText);
// Announce the new volume.
announceForAccessibility(newText);
current = newLevel;
}
}
本页面上的内容和代码示例受内容许可部分所述许可的限制。Java 和 OpenJDK 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-07-27。
[null,null,["最后更新时间 (UTC):2025-07-27。"],[],[],null,["# Support TalkBack in TV apps\n\nTV apps sometimes have use cases that make it difficult for users who rely on\n[TalkBack](/guide/topics/ui/accessibility/testing#talkback) to use the app. To provide a better TalkBack experience for these\nusers, review each of the sections in this guide and implement changes in your\napp where necessary. If your app uses custom views, you should also refer to the\n[corresponding guide](/training/tv/accessibility/custom-views) that describes how to support accessibility with custom\nviews.\n\nHandle nested views\n-------------------\n\nNested views can be hard for TalkBack users to navigate. Whenever possible, make\neither the parent or the child view focusable by TalkBack, but not both.\n\nTo make a view focusable by TalkBack, set the [`focusable`](/reference/android/view/View#attr_android:focusable) and the\n[`focusableInTouchMode`](/reference/android/view/View#attr_android:focusableInTouchMode) attribute to `true`. This step is necessary because\nsome TV devices might enter and exit touch mode while TalkBack is active.\n\nTo make a view non-focusable, it is sufficient to set the [`focusable`](/reference/android/view/View#attr_android:focusable)\nattribute to `false`. However, if the view is actionable (that is, its\ncorresponding `AccessibilityNodeInfo` has [`ACTION_CLICK`](/reference/android/view/accessibility/AccessibilityNodeInfo.AccessibilityAction#ACTION_CLICK)), it might still\nbe focusable.\n\nChange descriptions for Actions\n-------------------------------\n\nBy default, TalkBack announces \"Press select to activate\" for actionable views.\nFor some actions, the term \"activate\" might not be a good description. To\nprovide a more accurate description, you can change it: \n\n### Kotlin\n\n```kotlin\nfindViewById\u003cView\u003e(R.id.custom_actionable_view).accessibilityDelegate = object : View.AccessibilityDelegate() {\n override fun onInitializeAccessibilityNodeInfo(host: View, info: AccessibilityNodeInfo) {\n super.onInitializeAccessibilityNodeInfo(host, info)\n info.addAction(\n AccessibilityAction(\n AccessibilityAction.ACTION_CLICK.id,\n getString(R.string.custom_label)\n )\n )\n }\n}\n```\n\n### Java\n\n```java\nfindViewById(R.id.custom_actionable_view).setAccessibilityDelegate(new AccessibilityDelegate() {\n @Override\n public void onInitializeAccessibilityNodeInfo(View host, AccessibilityNodeInfo info) {\n super.onInitializeAccessibilityNodeInfo(host, info);\n AccessibilityAction action = new AccessibilityAction(\n AccessibilityAction.ACTION_CLICK.getId(), getString(R.string.custom_label));\n info.addAction(action);\n }\n});\n```\n\nAdd support for sliders\n-----------------------\n\nTalkBack on TV has special support for sliders. To enable slider mode, add\n[`ACTION_SET_PROGRESS`](/reference/android/view/accessibility/AccessibilityNodeInfo.AccessibilityAction#ACTION_SET_PROGRESS) to a view together with a [`RangeInfo`](/reference/android/view/accessibility/AccessibilityNodeInfo.RangeInfo) object.\n\nThe user enters the slider mode by pressing the center button of the TV remote.\nIn this mode, the arrow buttons generate [`ACTION_SCROLL_FORWARD`](/reference/android/view/accessibility/AccessibilityNodeInfo.AccessibilityAction#ACTION_SCROLL_FORWARD) and\n[`ACTION_SCROLL_BACKWARD`](/reference/android/view/accessibility/AccessibilityNodeInfo.AccessibilityAction#ACTION_SCROLL_BACKWARD) accessibility actions.\n\nThe following example implements a volume slider with levels from 1 to 10: \n\n### Kotlin\n\n```kotlin\n/**\n * This example only provides slider functionality for TalkBack users. Additional logic should\n * be added for other users. Such logic may reuse the increase and decrease methods.\n */\nclass VolumeSlider(context: Context?, attrs: AttributeSet?) : LinearLayout(context, attrs) {\n private val min = 1\n private val max = 10\n private var current = 5\n private var textView: TextView? = null\n\n init {\n isFocusable = true\n isFocusableInTouchMode = true\n val rangeInfo =\n AccessibilityNodeInfo.RangeInfo(\n AccessibilityNodeInfo.RangeInfo.RANGE_TYPE_INT,\n min.toFloat(),\n max.toFloat(),\n current.toFloat()\n )\n accessibilityDelegate =\n object : AccessibilityDelegate() {\n override fun onInitializeAccessibilityNodeInfo(host: View, info: AccessibilityNodeInfo) {\n super.onInitializeAccessibilityNodeInfo(host, info)\n info.addAction(AccessibilityNodeInfo.AccessibilityAction.ACTION_SET_PROGRESS)\n info.rangeInfo = rangeInfo\n }\n\n override fun performAccessibilityAction(host: View, action: Int, args: Bundle?): Boolean {\n if (action == AccessibilityNodeInfo.AccessibilityAction.ACTION_SCROLL_FORWARD.id) {\n increase()\n return true\n }\n if (action == AccessibilityNodeInfo.AccessibilityAction.ACTION_SCROLL_BACKWARD.id) {\n decrease()\n return true\n }\n return super.performAccessibilityAction(host, action, args)\n }\n }\n }\n\n override fun onFinishInflate() {\n super.onFinishInflate()\n textView = findViewById(R.id.text)\n textView!!.text = context.getString(R.string.level, current)\n }\n\n private fun increase() {\n update((current + 1).coerceAtMost(max))\n }\n\n private fun decrease() {\n update((current - 1).coerceAtLeast(min))\n }\n\n private fun update(newLevel: Int) {\n if (textView == null) {\n return\n }\n val newText = context.getString(R.string.level, newLevel)\n // Update the user interface with the new volume.\n textView!!.text = newText\n // Announce the new volume.\n announceForAccessibility(newText)\n current = newLevel\n }\n}\n```\n\n### Java\n\n```java\n/**\n * This example only provides slider functionality for TalkBack users. Additional logic should\n * be added for other users. Such logic can reuse the increase and decrease methods.\n */\npublic class VolumeSlider extends LinearLayout {\n private final int min = 1;\n private final int max = 10;\n private int current = 5;\n private TextView textView;\n\n public VolumeSlider(Context context, AttributeSet attrs) {\n super(context, attrs);\n setFocusable(true);\n setFocusableInTouchMode(true);\n RangeInfo rangeInfo = new RangeInfo(RangeInfo.RANGE_TYPE_INT, min, max, current);\n setAccessibilityDelegate(\n new AccessibilityDelegate() {\n @Override\n public void onInitializeAccessibilityNodeInfo(View host, AccessibilityNodeInfo info) {\n super.onInitializeAccessibilityNodeInfo(host, info);\n info.addAction(AccessibilityAction.ACTION_SET_PROGRESS);\n info.setRangeInfo(rangeInfo);\n }\n\n @Override\n public boolean performAccessibilityAction(View host, int action, Bundle args) {\n if (action == AccessibilityAction.ACTION_SCROLL_FORWARD.getId()) {\n increase();\n return true;\n }\n if (action == AccessibilityAction.ACTION_SCROLL_BACKWARD.getId()) {\n decrease();\n return true;\n }\n return super.performAccessibilityAction(host, action, args);\n }\n });\n }\n\n @Override\n protected void onFinishInflate() {\n super.onFinishInflate();\n textView = findViewById(R.id.text);\n textView.setText(getContext().getString(R.string.level, current));\n }\n\n private void increase() {\n update(Math.min(current + 1, max));\n }\n\n private void decrease() {\n update(Math.max(current - 1, min));\n }\n\n private void update(int newLevel) {\n if (textView == null) {\n return;\n }\n String newText = getContext().getString(R.string.level, newLevel);\n // Update the user interface with the new volume.\n textView.setText(newText);\n // Announce the new volume.\n announceForAccessibility(newText);\n current = newLevel;\n }\n}\n```"]]