【翻译】(23-补丁3)构建无障碍服务

【翻译】(23-补丁3)构建无障碍服务

 

see

http://developer.android.com/guide/topics/ui/accessibility/services.html

 

原文见

http://developer.android.com/guide/topics/ui/accessibility/services.html

 

-------------------------------

 

Building Accessibility Services

 

构建无障碍服务

 

-------------------------------

 

Topics

 

主题

 

* Manifest Declarations and Permissions 清单声明和权限

* Accessibility service declaration 无障碍服务声明

* Accessibility service configuration 无障碍服务配置

* AccessibilityService Methods AccessibilityService的方法 

* Getting Event Details 获取事件细节

* Example Code 示例代码

 

Key classes

 

关键类

 

AccessibilityService

AccessibilityServiceInfo

AccessibilityEvent

AccessibilityRecord

AccessibilityNodeInfo

 

See also

 

另见

 

Implementing Accessibility 实现无障碍

 

-------------------------------

 

An accessibility service is an application that provides user interface enhancements to assist users with disabilities, or who may temporarily be unable to fully interact with a device. For example, users who are driving, taking care of a young child or attending a very loud party might need additional or alternative interface feedback.

 

一个无障碍服务是一个应用程序，它提供用户界面一些增强功能以辅助有障碍的用户，或可能临时不能完全地与一台设备交互的用户。例如，正在驾驶中的用户，照顾一位幼儿，或参加一场非常吵杂的派对，可能需要额外的或可替换的界面反馈。

 

Android provides standard accessibility services, including TalkBack, and developers can create and distribute their own services. This document explains the basics of building an accessibility service.

 

Android提供标准无障碍服务，包括TalkBack，而且开发者可以创建和分发他们自己的服务。本文解释构建一个无障碍服务的基本知识。

 

The ability for you to build and deploy accessibility services was introduced with Android 1.6 (API Level 4) and received significant improvements with Android 4.0 (API Level 14). The Android Support Library was also updated with the release of Android 4.0 to provide support for these enhanced accessibility features back to Android 1.6. Developers aiming for widely compatible accessibility services are encouraged to use the Support Library and develop for the more advanced accessibility features introduced in Android 4.0.

 

你构建和部署无障碍服务的功能伴随Android 1.6（API级别4）被引入并且伴随Android 4.0（API级别14）而得到显著提高。Android支持库也伴随Android 4.0的发布而被更新以提供对这些增强的无障碍特性的支持向后直至Android 1.6。鼓励那些目标为广泛兼容的无障碍服务的开发者们使用支持库并且为在Android 4.0中被引入的更高级无障碍特性而开发。

 

-------------------------------

 

Manifest Declarations and Permissions

 

清单声明和权限

 

Applications that provide accessibility services must include specific declarations in their application manifests in order to be treated as an accessibility service by an Android system. This section explains the required and optional settings for accessibility services.

 

提供无障碍服务的应用程序必须在他们的应用程序清单中包含特定的声明以被一个Android系统视为一个无障碍服务。本章节解释对于无障碍服务来说必需的和可选的设置。

 

Accessibility service declaration

 

无障碍服务声明

 

In order to be treated as an accessibility service, your application must include the service element (rather than the activity element) within the application element in its manifest. In addition, within the service element, you must also include an accessibility service intent filter, as shown in the following sample:

 

为了被视为一个无障碍服务，你的应用程序必须在它的清单中的application元素内包含service元素（而非activity元素）。另外，在service元素内，你还必须包含一个无障碍服务意图过滤器，正如以下示例中所示：

 

-------------------------------

 

<application>

  <service android:name=".MyAccessibilityService"

      android:label="@string/accessibility_service_label">

    <intent-filter>

      <action android:name="android.accessibilityservice.AccessibilityService" />

    </intent-filter>

  </service>

</application>

 

-------------------------------

 

These declarations are required for all accessibility services deployed on Android 1.6 (API Level 4) or higher.

 

对于部署在Android 1.6（API级别4）或更高上的所有无障碍服务来说，这些声明是必需的。

 

Accessibility service configuration

 

无障碍服务配置

 

Accessibility services must also provide a configuration which specifies the types of accessibility events that the service handles and additional information about the service. The configuration of an accessibility service is contained in the AccessibilityServiceInfo class. Your service can build and set a configuration using an instance of this class and setServiceInfo() at runtime. However, not all configuration options are available using this method.

 

无障碍服务还必须提供一个配置，它指定服务处理的无障碍事件的类型以及关于服务的额外信息。一个无障碍服务的配置被包含在AccessibilityServiceInfo类中。你的服务可以在运行时使用此类的一个实例和setServiceInfo()来构建和设置一个配置。然而，使用此方法时不是所有配置选项都是可用的。

 

Beginning with Android 4.0, you can include a <meta-data> element in your manifest with a reference to a configuration file, which allows you to set the full range of options for your accessibility service, as shown in the following example:

 

从Android 4.0开始，你可以在你的清单中包含一个带有指向配置文件的引用的<meta-data>元素，它（注：配置文件）允许你设置你的无障碍服务的选项的完全范围，正如以下示例中所示：

 

-------------------------------

 

<service android:name=".MyAccessibilityService">

  ...

  <meta-data

    android:name="android.accessibilityservice"

    android:resource="@xml/accessibility_service_config" />

</service>

 

-------------------------------

 

This meta-data element refers to an XML file that you create in your application’s resource directory (<project_dir>/res/xml/accessibility_service_config.xml). The following code shows example contents for the service configuration file:

 

这个meta-data元素引用到一个XML文件，你在你的工程的资源目录中创建它（<project_dir>/res/xml/accessibility_service_config.xml）。以下代码展示服务配置文件的示例内容：

 

-------------------------------

 

<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"

    android:description="@string/accessibility_service_description"

    android:packageNames="com.example.android.apis"

    android:accessibilityEventTypes="typeAllMask"

    android:accessibilityFlags="flagDefault"

    android:accessibilityFeedbackType="feedbackSpoken"

    android:notificationTimeout="100"

    android:canRetrieveWindowContent="true"

    android:settingsActivity="com.example.android.accessibility.ServiceSettingsActivity"

/>

 

-------------------------------

 

One of the most important functions of the accessibility service configuration parameters is to allow you to specify what types of accessibility events your service can handle. Being able to specify this information enables accessibility services to cooperate with each other, and allows you as a developer the flexibility to handle only specific events types from specific applications. The event filtering can include the following criteria:

 

无障碍服务配置参数的其中一个最重要的作用是允许你指定你的服务可以处理什么类型的无障碍事件。能够指定这个信息使无障碍服务能够相互协作，并且允许作为开发者的你具有只处理来自指定应用程序的指定事件类型的灵活性。事件过滤可以包含以下条件：

 

* Package Names - Specify the package names of applications whose accessibility events you want your service to handle. If this parameter is omitted, your accessibility service is considered available to service accessibility events for any application. This parameter can be set in the accessibility service configuration files with the android:packageNames attribute as a comma-separated list, or set using the AccessibilityServiceInfo.packageNames member.

 

* 包名称——指定应用程序的包名称，你想你的服务处理它的无障碍事件。如果这个参数被忽略，那么你的无障碍服务被认为是可用于服务（注：这里的service可能是名词）任意应用程序的无障碍事件。此参数可以在无障碍服务配置文件中用android:packageNames设置为一个逗号分隔列表，或者使用AccessibilityServiceInfo.packageNames成员来设置。

 

* Event Types - Specify the types of accessibility events you want your service to handle. This parameter can be set in the accessibility service configuration files with the android:accessibilityEventTypes attribute as a comma-separated list, or set using the AccessibilityServiceInfo.eventTypes member.

 

* 事件类型——指定你想你的服务处理的无障碍事件的类型。这个参数可以在无障碍服务配置文件中用android:accessibilityEventTypes属性设置为一个逗号分隔列表，或者使用AccessibilityServiceInfo.eventTypes成员来设置。

 

For more information about the XML attributes which can be used in the accessibility service configuration file, follow these links to the reference documentation:

 

想获得关于可以被用在无障碍服务配置文件中的XML属性的更多信息，请跟随这些指向参考文档的链接：

 

* android:description

* android:packageNames

* android:accessibilityEventTypes

* android:accessibilityFlags

* android:accessibilityFeedbackType

* android:notificationTimeout

* android:canRetrieveWindowContent

* android:settingsActivity

 

For more information about which configuration settings can be dynamically set at runtime, see the AccessibilityServiceInfo reference documentation.

 

想获得关于哪些配置设置可以在运行时被动态设置，请参见AccessibilityServiceInfo的参考文档。

 

-------------------------------

 

AccessibilityService Methods

 

AccessibilityService的方法

 

An application that provides accessibility service must extend the AccessibilityService class and override the following methods from that class. These methods are presented in the order in which they are called by the Android system, from when the service is started (onServiceConnected()), while it is running (onAccessibilityEvent(), onInterrupt()) to when it is shut down (onUnbind()).

 

一个提供无障碍服务的应用程序必须扩展AccessibilityService类并且从那个类中覆盖以下方法。这些方法依照它们被Android系统调用的次序而来呈现，从服务被启动开始（onServiceConnected()），当它正在运行（onAccessibilityEvent()，onInterrupt()）直至当它被关闭（onUnbind()）。

 

* onServiceConnected() - (optional) This system calls this method when it successfully connects to your accessibility service. Use this method to do any one-time setup steps for your service, including connecting to user feedback system services, such as the audio manager or device vibrator. If you want to set the configuration of your service at runtime or make one-time adjustments, this is a convenient location from which to call setServiceInfo().

 

* onServiceConnected()——（可选的）系统调用此方法，当它成功地连接到你的无障碍服务。使用此方法以为你的服务执行任意一次性配置步骤，包括连接到用户反馈的系统服务，诸如音频管理器或设备振动器。如果你想在运行时设置你的设备的配置或者作一次性的调整，这是一个方便的位置，从这里调用setServiceInfo()。

 

* onAccessibilityEvent() - (required) This method is called back by the system when it detects an AccessibilityEvent that matches the event filtering parameters specified by your accessibility service. For example, when the user clicks a button or focuses on a user interface control in an application for which your accessibility service is providing feedback. When this happens, the system calls this method of your service with the associated AccessibilityEvent, which you can then interpret and provide feedback to the user. This method may be called many times over the lifecycle of your service.

 

* onAccessibilityEvent()——（必需的）这个方法被系统回调，当它检测一个AccessibilityEvent匹配被你的无障碍服务指定的事件过滤参数。例如，当用户点击一个按钮或把焦点移到你的无障碍服务正在为其提供反馈的应用程序的一个用户界面控件上。当这发生时，系统用相关的AccessibilityEvent调用你的服务的这个方法，然后你可以解析它并且提供反馈给用户。这个方法可能在你的服务的整个生命周期中被调用许多次。

 

* onInterrupt() - (required) This method is called when the system wants to interrupt the feedback your service is providing, usually in response to a user taking action, such as moving focus to a different user interface control than the one for which you are currently providing feedback. This method may be called many times over the lifecycle of your service.

 

* onInterrupt()——（必需的）这个方法被调用，当系统想中断你的服务正在提供的反馈，通常为了响应一个用户谈话动作，诸如移动焦点到一个不同的用户界面控件而非你当前正在提供反馈的那个控件。在你的服务的整个生命周期内这个方法可能被调用多次。

 

* onUnbind() - (optional) This method is called when the system is about to shutdown the accessibility service. Use this method to do any one-time shutdown procedures, including de-allocating user feedback system services, such as the audio manager or device vibrator.

 

* onUnbind()——（可选的）这个方法被调用，当系统打算关闭无障碍服务时。使用此方法来做任意一次性关闭过程，包括释放（注：取消分配）用户反馈的系统服务，诸如音频管理器或设备振动器。

 

These callback methods provide the basic structure for your accessibility service. It is up to you to decide on how to process data provided by the Android system in the form of AccessibilityEvent objects and provide feedback to the user.

 

这些回调方法提供你的无障碍服务的基本结构。这取决于你决定如何处理Android系统以AccessibilityEvent对象的形式提供的数据以及提供反馈给用户。

 

-------------------------------

 

Getting Event Details

 

获取事件细节

 

The Android system provides information to accessibility services about the user interface interaction through AccessibilityEvent objects. Prior to Android 4.0, the information available in an accessibility event, while providing a significant amount of detail about a user interface control selected by the user, typically provided limited contextual information. In many cases, this missing context information might be critical to understanding the meaning of the selected control.

 

Android系统通过AccessibilityEvent对象提供关于用户界面交互的信息给无障碍服务。在Android 4.0之前，一个无障碍事件中的可用信息，虽然提供关于被用户选择的用户界面控件的巨大数量细节，但通常只提供有限的上下文相关信息。在许多情况下，缺少的上下文信息对理解被选择控件的含义可能是关键的。

 

A typical example of an interface where context is of critical importance is a calendar or day planner. If a user selects a 4:00 PM time slot in a Monday to Friday day list and the accessibility service announces “4 PM”, but fails to indicate this is a Friday a Monday, the month or day, this is hardly ideal feedback for the user. In this case, the context of a user interface control is of critical importance to a user who wants to schedule a meeting.

 

上下文是至关重要的（注：关键的重点），出现这种情况的界面的一个典型示例是日历或日程安排（注：对未来的日记）。如果一位用户在一个星期一至星期五的日期列表中选择一个下午4:00的时间槽（注：时隙，时间空档）而无障碍服务宣称“下午4点”，但未能指出这是一个星期五还是一个星期一（注：此处貌似少了一个or），月还是日，这对于用户来说几乎不是理想的反馈。在这种情况下，用户界面控件的上下文对于希望计划一个约会的用户来说是至关重要的。

 

Android 4.0 significantly extends the amount of information that an accessibility service can obtain about an user interface interaction by composing accessibility events based on the view hierarchy. A view hierarchy is the set of user interface components that contain the component (its parents) and the user interface elements that may be contained by that component (its children). In this way, the Android system can provide much richer detail about accessibility events, allowing accessibility services to provide more useful feedback to users.

 

Android 4.0通过基于视图层级组合无障碍事件来显著地扩展大量信息，使一个无障碍服务可以获得关于一个用户界面交互的信息。一个视图层级是用户界面组件的集合，它包含组件（它的父组件）和可能被那个组件包含的用户界面元素（它的子组件）。通过这种方式，Android系统可以提供关于无障碍事件的更丰富细节，允许无障碍服务向用户提供更有用的反馈。

 

An accessibility service gets information about an user interface event through an AccessibilityEvent passed by the system to the service’s onAccessibilityEvent() callback method. This object provides details about the event, including the type of object being acted upon, its descriptive text and other details. Starting in Android 4.0 (and supported in previous releases through the AccessibilityEventCompat object in the Support Library), you can obtain additional information about the event using these calls:

 

无障碍服务通过被系统传递给服务的onAccessibilityEvent()回调方法的一个AccessibilityEvent来获得关于用户界面事件的信息。这个对象提供关于该事件的细节，包括动作正在被施加在的对象的类型，它的描述文本和其它细节。在Android 4.0开始（以及在之前的发布版中通过支持库中的AccessibilityEventCompat对象来支持的版本），你可以使用这些调用来取得关于该事件的额外信息：

 

* AccessibilityEvent.getRecordCount() and getRecord(int) - These methods allow you to retrieve the set of AccessibilityRecord objects which contributed to the AccessibilityEvent passed to you by the system, which can provide more context for your accessibility service.

 

* AccessibilityEvent.getRecordCount()和getRecord(int)——这些方法允许你取出AccessibilityRecord对象的集合，它们组成（注：促成，导致，贡献给）被系统传递给你的AccessibilityEvent，它可以为你的无障碍服务提供更多上下文。

 

* AccessibilityEvent.getSource() - This method returns an AccessibilityNodeInfo object. This object allows you to request the parents and children of the component that originated the accessibility event and investigate their contents and state in order to provide

 

* AccessibilityEvent.getSource()——这个方法返回一个AccessibilityNodeInfo对象，该对象允许你请求引发无障碍事件的该组件的父组件与子组件，和调查它们的内容和状态以便提供（注：此处原文怀疑有遗漏）

 

-------------------------------

 

Important: The ability to investigate the full view hierarchy from an AccessibilityEvent potentially exposes private user information to your accessibility service. For this reason, your service must request this level of access through the accessibility service configuration XML file, by including the canRetrieveWindowContent attribute and setting it to true. If you do not include this setting in your service configuration xml file, calls to getSource() fail.

 

重要：从一个AccessibilityEvent中调查完全视图层级的能力隐式地暴露私有用户信息给你的无障碍服务。出于这个原因，你的服务必须通过无障碍服务配置XML文件请求这个级别的访问权，通过包含canRetrieveWindowContent属性和设置它为true。如果你不在你的服务配置xml文件中包含这个设置，那么对getSource()的调用会失败。

 

-------------------------------

 

-------------------------------

 

Example Code

 

示例代码

 

The API Demo project contains two samples which can be used as a starting point for generating accessibility services (<sdk>/samples/<platform>/ApiDemos/src/com/example/android/apis/accessibility):

 

API示例工程包含两个示例，它们可以被用作生成无障碍服务的一个起点（<sdk>/samples/<platform>/ApiDemos/src/com/example/android/apis/accessibility）：

 

* ClockBackService - This service is based on the original implementation of AccessibilityService and can be used as a base for developing basic accessibility services that are compatible with Android 1.6 (API Level 4) and higher.

 

* ClockBackService——这个服务是基于AccessibilityService的最初实现，并且可以被用作开发兼容Android 1.6（API级别4）和更高的基本无障碍服务的一个基础。

 

* TaskBackService - This service is based on the enhanced accessibility APIs introduced in Android 4.0 (API Level 14). However, you can use the Android Support Libary to substitute classes introduced in later API levels (e.g., AccessibilityRecord, AccessibilityNodeInfo ) with equivalent support package classes (e.g., AccessibilityRecordCompat, AccessibilityNodeInfoCompat ) to make this example work with API versions back to Android 1.6 (API Level 4).

 

* TaskBackService——这个服务是基于在Android 4.0（API级别14）中引入的增强API。然而，你可以使用Android支持库来代替在较新的API级别中引入的类（例如，AccessibilityRecordCompat，AccessibilityNodeInfoCompat）以使这个示例工作于后退至Android 1.6（API级别4）的API版本。

 

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.

 

除特别说明外，本文在Apache 2.0下许可。细节和限制请参考内容许可证。

 

Android 4.0 r1 - 07 Apr 2012 1:06

 

-------------------------------

 

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

 

此页部分内容，是基于Android开源项目所创建和共享的工作，并且根据知识共享2.5署名许可证描述的条款来使用的修改版。

 

（本人翻译质量欠佳，请以官方最新内容为准，或者参考其它翻译版本：

* ソフトウェア技術ドキュメントを勝手に翻訳

http://www.techdoctranslator.com/android

* Ley's Blog

http://leybreeze.com/blog/

* 农民伯伯

http://www.cnblogs.com/over140/

* Android中文翻译组

http://androidbox.sinaapp.com/

）