การสนับสนุนการช่วยเหลือพิเศษเกี่ยวกับมุมมองที่กำหนดเองบน Android TV
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
แม้ว่าแอป Android TV จำนวนมากจะสร้างด้วยคอมโพเนนต์ของ Android ที่มาพร้อมเครื่อง
ควรคำนึงถึงความสามารถเข้าถึงได้ง่ายของบุคคลที่สาม
ของเฟรมเวิร์กหรือคอมโพเนนต์ โดยเฉพาะเมื่อใช้มุมมองที่กำหนดเอง
คอมโพเนนต์มุมมองที่กำหนดเองซึ่งเชื่อมต่อกับ OpenGL หรือ Canvas โดยตรงอาจทำงานได้ไม่ดี
ด้วยบริการการช่วยเหลือพิเศษ เช่น TalkBack และการเข้าถึงด้วยสวิตช์
พิจารณาปัญหาต่อไปนี้ที่อาจเกิดขึ้นเมื่อมีการเปลี่ยน TalkBack
ใน:
- โฟกัสการช่วยเหลือพิเศษ (สี่เหลี่ยมผืนผ้าสีเขียว) อาจหายไปในแอป
- โฟกัสการช่วยเหลือพิเศษอาจเลือกขอบเขตของทั้งหน้าจอ
- โฟกัสการช่วยเหลือพิเศษอาจย้ายไม่ได้
- ปุ่มทิศทาง 4 ทิศทางบน D-pad อาจไม่ส่งผลใดๆ แม้ว่าโค้ดของคุณจะจัดการอยู่ก็ตาม
หากพบปัญหาเหล่านี้ในแอป ให้ตรวจสอบว่า
แสดง AccessibilityNodeInfo
ต้นไม้สำหรับบริการการช่วยเหลือพิเศษ
ส่วนที่เหลือของคู่มือนี้จะอธิบายวิธีแก้ไขและแนวทางปฏิบัติแนะนำในการแก้ไขปัญหาเหล่านี้
บริการการช่วยเหลือพิเศษจะดูแลจัดการเหตุการณ์ D-pad
สาเหตุของปัญหานี้คือการช่วยเหลือพิเศษใช้เหตุการณ์สําคัญ
บริการต่างๆ
รูปที่ 1 แผนภาพแสดงการทำงานของระบบเมื่อเปิดและปิด TalkBack
ดังที่แสดงในรูปที่ 1 เมื่อ TalkBack เปิดอยู่ เหตุการณ์ D-pad
ไม่ได้ส่งไปยังตัวแฮนเดิล D-pad ที่นักพัฒนาซอฟต์แวร์กำหนด แต่
บริการการช่วยเหลือพิเศษจะได้รับเหตุการณ์สำคัญเพื่อให้ย้าย
โฟกัสการช่วยเหลือพิเศษ เนื่องจากคอมโพเนนต์ Android ที่กำหนดเองจะไม่แสดงโดยค่าเริ่มต้น
ข้อมูลเกี่ยวกับบริการช่วยเหลือพิเศษเกี่ยวกับตำแหน่งบนหน้าจอ
บริการการช่วยเหลือพิเศษจะย้ายโฟกัสการช่วยเหลือพิเศษเพื่อไฮไลต์บริการไม่ได้
บริการการเข้าถึงอื่นๆ ก็ได้รับผลกระทบคล้ายๆ กัน เช่น เหตุการณ์ D-pad ก็อาจได้รับผลกระทบด้วย
ใช้เมื่อใช้การเข้าถึงด้วยสวิตช์
เนื่องจากมีการส่งเหตุการณ์ D-pad ไปยังบริการการช่วยเหลือพิเศษ และ
บริการนั้นจะไม่รู้ว่าคอมโพเนนต์ UI อยู่ตรงไหนในมุมมองที่กำหนดเอง
คุณต้องใช้ AccessibilityNodeInfo เพื่อให้แอปส่งต่อ
เหตุการณ์สำคัญได้อย่างถูกต้อง
หากต้องการให้บริการการช่วยเหลือพิเศษด้วยข้อมูลที่เพียงพอเกี่ยวกับ
ตำแหน่งและคำอธิบายของมุมมองที่กำหนดเอง ใช้ AccessibilityNodeInfo
เพื่อแสดงรายละเอียดของแต่ละคอมโพเนนต์
ในการกำหนดความสัมพันธ์เชิงตรรกะของมุมมองเพื่อให้บริการการเข้าถึงสามารถ
จัดการสิ่งที่มุ่งเน้น, ใช้ ExploreByTouchHelper
และตั้งค่าโดยใช้
ViewCompat.setAccessibilityDelegate(View, AccessibilityDelegateCompat)
สำหรับมุมมองที่กำหนดเอง
เมื่อใช้งาน ExploreByTouchHelper ให้ลบล้างเมธอดนามธรรม 4 วิธีต่อไปนี้
Kotlin
// Return the virtual view ID whose view is covered by the input point (x, y).
protected fun getVirtualViewAt(x: Float, y: Float): Int
// Fill the virtual view ID list into the input parameter virtualViewIds.
protected fun getVisibleVirtualViews(virtualViewIds: List<Int>)
// For the view whose virtualViewId is the input virtualViewId, populate the
// accessibility node information into the AccessibilityNodeInfoCompat parameter.
protected fun onPopulateNodeForVirtualView(virtualViewId: Int, @NonNull node: AccessibilityNodeInfoCompat)
// Set the accessibility handling when perform action.
protected fun onPerformActionForVirtualView(virtualViewId: Int, action: Int, @Nullable arguments: Bundle): Boolean
Java
// Return the virtual view ID whose view is covered by the input point (x, y).
protected int getVirtualViewAt(float x, float y)
// Fill the virtual view ID list into the input parameter virtualViewIds.
protected void getVisibleVirtualViews(List<Integer> virtualViewIds)
// For the view whose virtualViewId is the input virtualViewId, populate the
// accessibility node information into the AccessibilityNodeInfoCompat parameter.
protected void onPopulateNodeForVirtualView(int virtualViewId, @NonNull AccessibilityNodeInfoCompat node)
// Set the accessibility handling when perform action.
protected boolean onPerformActionForVirtualView(int virtualViewId, int action, @Nullable Bundle arguments)
สำหรับรายละเอียดเพิ่มเติม โปรดดู Google I/O 2013 - การเปิดใช้คนตาบอดและสายตาเลือนราง
การช่วยเหลือพิเศษใน Android
หรืออ่านเพิ่มเติมเกี่ยวกับการป้อนข้อมูลกิจกรรมการช่วยเหลือพิเศษ
แนวทางปฏิบัติแนะนำ
ตัวอย่าง
ดูตัวอย่างการช่วยเหลือพิเศษในมุมมองที่กำหนดเองสำหรับ Android TV เพื่อดูแนวทางปฏิบัติแนะนำสำหรับ
เพิ่มการสนับสนุนการช่วยเหลือพิเศษลงในแอปที่ใช้มุมมองที่กำหนดเอง
ตัวอย่างเนื้อหาและโค้ดในหน้าเว็บนี้ขึ้นอยู่กับใบอนุญาตที่อธิบายไว้ในใบอนุญาตการใช้เนื้อหา Java และ OpenJDK เป็นเครื่องหมายการค้าหรือเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-07-27 UTC
[[["เข้าใจง่าย","easyToUnderstand","thumb-up"],["แก้ปัญหาของฉันได้","solvedMyProblem","thumb-up"],["อื่นๆ","otherUp","thumb-up"]],[["ไม่มีข้อมูลที่ฉันต้องการ","missingTheInformationINeed","thumb-down"],["ซับซ้อนเกินไป/มีหลายขั้นตอนมากเกินไป","tooComplicatedTooManySteps","thumb-down"],["ล้าสมัย","outOfDate","thumb-down"],["ปัญหาเกี่ยวกับการแปล","translationIssue","thumb-down"],["ตัวอย่าง/ปัญหาเกี่ยวกับโค้ด","samplesCodeIssue","thumb-down"],["อื่นๆ","otherDown","thumb-down"]],["อัปเดตล่าสุด 2025-07-27 UTC"],[],[],null,["# Custom view accessibility support on Android TV\n\nWhile many Android TV apps are built with native Android components, it's\nalso important to consider the accessibility of third-party\nframeworks or components, especially when using [custom views](https://developer.android.com/guide/topics/ui/custom-components).\n\nCustom view components interfacing directly with OpenGL or Canvas might not work well\nwith accessibility services like Talkback and Switch Access.\n\nConsider some of the following issues that might occur with Talkback switched\non:\n\n- The accessibility focus (a green rectangle) might disappear in your app.\n- The accessibility focus might select the boundary of the whole screen.\n- The accessibility focus might not be movable.\n- The four direction keys on the D-pad might have no effect, even if your code is handling them.\n\n\u003cbr /\u003e\n\nIf you observe any of these issues in your app, check that your\napp exposes its [`AccessibilityNodeInfo`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo)\ntree to the accessibility services.\n\nThe remainder of this guide provides some solutions and best practices to address these issues.\n\nD-pad events are consumed by accessibility services\n---------------------------------------------------\n\nThe root cause of this issue is that key events are consumed by accessibility\nservices.\n\n\n**Figure 1.** Diagrams depicting how the system functions with Talkback on and off.\n\nAs illustrated in figure 1, when Talkback is switched on, D-pad events\nare not passed to the D-pad handler defined by developer. Instead,\naccessibility services receive the key events so they can move the\naccessibility focus. Because custom Android components don't by default expose\ninformation to accessibility services about their position on the screen,\naccessibility services can't move the accessibility focus to highlight them.\n\nOther accessibility services are similarly affected: D-pad events might also be\nconsumed when using Switch Access.\n\nBecause D-pad events are submitted to accessibility services, and\nthat service doesn't know where UI components are in a custom view,\nyou must implement `AccessibilityNodeInfo` for your app to forward the\nkey events correctly.\n\nExpose information to accessibility services\n--------------------------------------------\n\nTo provide accessibility services with sufficient information about the\nlocation and description of custom views, implement [`AccessibilityNodeInfo`](/reference/android/view/accessibility/AccessibilityNodeInfo)\nto expose details for each component.\nTo define the logical relationship of views so that accessibility services can\nmanage focus, implement [`ExploreByTouchHelper`](https://developer.android.com/reference/androidx/customview/widget/ExploreByTouchHelper)\nand set it using\n[`ViewCompat.setAccessibilityDelegate(View, AccessibilityDelegateCompat)`](https://developer.android.com/reference/androidx/core/view/ViewCompat#setAccessibilityDelegate(android.view.View,%20androidx.core.view.AccessibilityDelegateCompat))\nfor custom views.\n\nWhen implementing `ExploreByTouchHelper`, override its four abstract methods: \n\n### Kotlin\n\n```kotlin\n// Return the virtual view ID whose view is covered by the input point (x, y).\nprotected fun getVirtualViewAt(x: Float, y: Float): Int\n\n// Fill the virtual view ID list into the input parameter virtualViewIds.\nprotected fun getVisibleVirtualViews(virtualViewIds: List\u003cInt\u003e)\n\n// For the view whose virtualViewId is the input virtualViewId, populate the\n// accessibility node information into the AccessibilityNodeInfoCompat parameter.\nprotected fun onPopulateNodeForVirtualView(virtualViewId: Int, @NonNull node: AccessibilityNodeInfoCompat)\n\n// Set the accessibility handling when perform action.\nprotected fun onPerformActionForVirtualView(virtualViewId: Int, action: Int, @Nullable arguments: Bundle): Boolean\n```\n\n### Java\n\n```java\n// Return the virtual view ID whose view is covered by the input point (x, y).\nprotected int getVirtualViewAt(float x, float y)\n\n// Fill the virtual view ID list into the input parameter virtualViewIds.\nprotected void getVisibleVirtualViews(List\u003cInteger\u003e virtualViewIds)\n\n// For the view whose virtualViewId is the input virtualViewId, populate the\n// accessibility node information into the AccessibilityNodeInfoCompat parameter.\nprotected void onPopulateNodeForVirtualView(int virtualViewId, @NonNull AccessibilityNodeInfoCompat node)\n\n// Set the accessibility handling when perform action.\nprotected boolean onPerformActionForVirtualView(int virtualViewId, int action, @Nullable Bundle arguments)\n```\n\nFor more details, watch [Google I/O 2013 - Enabling Blind and Low-Vision\nAccessibility on Android](https://www.youtube.com/watch?v=ld7kZRpMGb8&t=1196)\nor read more about [populating accessibility events](https://developer.android.com/guide/topics/ui/accessibility/custom-views#populate-events).\n\nBest practices\n--------------\n\n- **Required:** [`AccessibilityNodeInfo.getBoundsInScreen()`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#getBoundsInScreen(android.graphics.Rect))\n must define the position of the component.\n\n- **Required:** [`AccessibilityNodeInfo.setVisibleToUser()`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#setVisibleToUser(boolean))\n must reflect the visibility of the component.\n\n- **Required:** [`AccessibilityNodeInfo.getContentDescription()`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#getContentDescription())\n must specify the content description for Talkback to announce.\n\n- Specify [`AccessibilityNodeInfo.setClassName()`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#setClassName(java.lang.CharSequence))\n so services can distinguish the component type.\n\n- When implementing [`performAction()`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#performAction(int)),\n reflect the action using a corresponding [`AccessibilityEvent`](https://developer.android.com/reference/android/view/accessibility/AccessibilityEvent).\n\n- To implement more action types, such as `ACTION_CLICK`, invoke\n [`AccessibilityNodeInfo.addAction(ACTION_CLICK)`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#addAction(android.view.accessibility.AccessibilityNodeInfo.AccessibilityAction))\n using the corresponding logic in `performAction()`.\n\n- When applicable, reflect the component state for [`setFocusable()`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#setFocusable(boolean)),\n [`setClickable()`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#setClickable(boolean)),\n [`setScrollable()`](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#setScrollable(boolean)),\n and similar methods.\n\n- Review the documentation for [`AccessibilityNodeInfo`](/reference/android/view/accessibility/AccessibilityNodeInfo)\n to identify other ways in which accessibility services can better interact with\n your components.\n\nSample\n------\n\nConsult the [custom view accessibility sample for Android TV](/training/tv/accessibility/custom-views-sample) to see best practices for\nadding accessibility support to apps using custom views."]]
