无障碍属性

设置组件的无障碍属性和事件，以充分利用无障碍功能。

说明：

从API version 10 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

accessibilityGroup

accessibilityGroup(value: boolean)

设置是否启用无障碍分组。启用无障碍分组后，组件及其子组件作为一整个可选组件，无障碍服务不再关注子组件内容。

若组件启用无障碍分组，当组件不包含通用文本属性，同时未设置无障碍文本时，将默认拼接其子组件的通用文本属性作为组件的合并文本。若某一子组件没有通用文本属性，则忽略该子组件不进行拼接，此时合并文本不使用子组件的无障碍文本。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityGroup¹⁴⁺

accessibilityGroup(isGroup: boolean, accessibilityOptions: AccessibilityOptions)

设置是否启用无障碍分组。启用无障碍分组后，组件及其子组件作为一整个可选组件，无障碍服务不再关注子组件内容。

若组件启用无障碍分组，当组件不包含通用文本属性，同时未设置无障碍文本时，将默认拼接其子组件的通用文本属性作为组件的合并文本。若某一子组件没有通用文本属性，则忽略该子组件不进行拼接。

通过accessibilityPreferred启用优先拼接无障碍文本进行朗读后，将优先拼接其子组件的无障碍文本属性作为组件的合并文本。若某一子组件未设置无障碍文本，则继续拼接该子组件的通用文本属性，若该子组件没有通用文本属性，则忽略该子组件不进行拼接。

卡片能力： 从API version 14开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

AccessibilityOptions¹⁴⁺对象说明

系统能力： SystemCapability.ArkUI.ArkUI.Full

accessibilityText

accessibilityText(value: string)

设置无障碍文本。当组件不包含文本属性时，开发人员可通过设置无障碍文本属性，使不包含文字信息的组件能够播报无障碍文本的内容。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityText¹²⁺

accessibilityText(text: Resource)

设置无障碍文本，支持通过Resource引用资源文件。当组件不包含文本属性时，开发人员可通过设置无障碍文本属性，使不包含文字信息的组件能够播报无障碍文本的内容。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityDescription

accessibilityDescription(value: string)

设置无障碍说明。该属性用于为用户进一步说明当前组件，开发人员可为组件设置相对较详细的解释文本，帮助用户理解将要执行的操作。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityDescription¹²⁺

accessibilityDescription(description: Resource)

设置无障碍说明，支持通过Resource引用资源文件。该属性用于为用户进一步说明当前组件，开发人员可为组件设置相对较详细的解释文本，帮助用户理解将要执行的操作。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityLevel

accessibilityLevel(value: string)

设置无障碍重要性。该属性用于控制某个组件是否可被无障碍辅助服务所识别。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityVirtualNode¹¹⁺

accessibilityVirtualNode(builder: CustomBuilder)

设置无障碍虚拟子节点。对自绘制组件传入一个自定义的CustomBuilder，该CustomBuilder中的组件在后端仅做布局不做显示，辅助应用获取无障碍节点信息时会返回CustomBuilder中的节点信息。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityChecked¹³⁺

accessibilityChecked(isCheck: boolean)

无障碍节点是否选中的状态维护，用于支持多选的情况使用，表示组件是否被选中。

卡片能力： 从API version 13开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 13开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilitySelected¹³⁺

accessibilitySelected(isSelect: boolean)

无障碍节点是否选中的状态维护，用于支持单选的情况使用，表示组件是否被选中。

卡片能力： 从API version 13开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 13开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityRole¹⁸⁺

accessibilityRole(role: AccessibilityRoleType)

设置无障碍组件类型，特定组件类型有特定的朗读方式，可以根据应用诉求，修改组件类型，用于控制无障碍模式下对组件的朗读方式和朗读内容。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

AccessibilityRoleType¹⁸⁺枚举说明

定义组件的屏幕朗读功能角色类型。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

accessibilityNextFocusId¹⁸⁺

accessibilityNextFocusId(nextId: string)

指定走焦过程中组件的下一个焦点。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityDefaultFocus¹⁸⁺

accessibilityDefaultFocus(focus: boolean)

设置屏幕朗读当前页默认首焦点。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityUseSamePage¹⁸⁺

accessibilityUseSamePage(pageMode: AccessibilitySamePageMode)

针对UIExtensionComponent等子树场景中可能出现的跳焦问题，可以通过设置accessibilityUseSamePage属性来解决。由于UEApage事件（由UIExtensionComponent拉起来的进程的page事件）和宿主page事件发送时序的问题，可能会导致焦点从当前组件移动到另一个组件，这种现象即为”跳焦”。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

AccessibilitySamePageMode¹⁸⁺枚举说明

当前UIExtensionComponent和宿主应用的同page模式。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

accessibilityScrollTriggerable¹⁸⁺

accessibilityScrollTriggerable(isTriggerable: boolean)

设置无障碍节点是否支持屏幕朗读滚动操作。当屏幕朗读在焦点切换时，若容器内当前页面无可聚焦的组件，会发起一次自动滚动操作。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityTextHint¹²⁺

accessibilityTextHint(value: string)

设置组件的文本提示信息，供无障碍辅助应用查询。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

accessibilityFocusDrawLevel¹⁹⁺

accessibilityFocusDrawLevel(drawLevel: FocusDrawLevel)

无障碍焦点绿框的绘制层级设置功能。

说明：

1. 在聚焦节点层级绘制获焦无障碍绿框，默认使用该层级绘制，由于绘制组件数顺序以及图形绘制顺序，绘制绿框会被父组件或者z序更高的兄弟组件遮挡裁切。

2. 在Z序顶层绘制绿框情况下，可以避免由于组件遮挡、裁切导致无障碍绿框被裁切遮挡。但由于具备较高的绘制层级，如果需要交互过程中，需要遮挡当前获焦的组件，并且不希望显示无障碍绿框则不适合使用这种配置。

卡片能力： 从API version 19开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

示例

示例1（设置无障碍文本和无障碍说明）

该示例主要演示accessibilityText无障碍文本和accessibilityDescription无障碍说明的播报内容。

// xxx.ets
@Entry
@Component
struct Index {

  @Builder customAccessibilityNode() {
    Column() {
      Text(`virtual node`)
    }
    .width(10)
    .height(10)
  }

  build() {
    Row() {
      Column() {
        Text("文本1")
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        Text("文本2")
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
      .accessibilityGroup(true)
      .accessibilityLevel("yes")
      .accessibilityText("分组") // 无障碍文本的内容，若组件既拥有文本属性又拥有无障碍文本属性，则组件被选中时，仅播报无障碍文本内容。
      .accessibilityDescription("Column组件可以被选中，播报的内容是“分组”")
      .accessibilityVirtualNode(this.customAccessibilityNode)
      .accessibilityChecked(true)
      .accessibilitySelected(undefined)
    }
    .height('100%')
  }
}

示例2（设置无障碍组）

该示例主要演示优先使用子组件的无障碍文本进行朗读。

// xxx.ets
@Entry
@Component
struct Focus {
  build() {
    Column({ space: 10 }) {
      Text('123456')
        .focusable(true)
        .borderRadius(5)
        .accessibilityText("有accessibility有text优先读accessibility")
        .accessibilityLevel("yes")
      Button().accessibilityLevel("yes").accessibilityText("accessibility无text 读accessibility")
      Button("无accessibility有text 读text").accessibilityLevel("yes")
      Button()
      Button('btn123').accessibilityText("有accessibility有text btn123").accessibilityLevel("yes")
      Button('btn123').accessibilityLevel("yes")
    }
    .accessibilityGroup(true, { accessibilityPreferred: true })
    .borderWidth(5)
    .width('100%')
    .height('100%')
  }
}

示例3（设置首焦点和组件的下一个焦点）

该示例主要演示accessibilityDefaultFocus屏幕朗读当前页默认首焦点和accessibilityNextFocusId走焦过程中组件的下一个焦点。

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column({ space: 20 }) {
      Text('Text Demo 1')
        .fontSize(50)
        .accessibilityLevel('yes')
        .accessibilityNextFocusId('text3')
      Text('Text Demo 2')
        .id('text2')
        .fontSize(50)
        .accessibilityLevel('yes')
        .accessibilityDefaultFocus(true)  // 设置该组件为屏幕朗读当前页默认首焦点
        .accessibilityNextFocusId('text4')
      Text('Text Demo 3')
        .id('text3')
        .fontSize(50)
        .accessibilityLevel('yes')
        .accessibilityNextFocusId('text2')
      Text('Text Demo 4')
        .id('text4')
        .fontSize(50)
        .accessibilityLevel('yes')
    }
    .height('100%')
    .width('100%')
  }
}

示例4（设置无障碍组件类型和文本提示信息）

该示例主要演示accessibilityRole无障碍组件类型和accessibilityTextHint供无障碍辅助应用查询的组件的文本提示信息。

// xxx.ets
@Entry
@Component
struct Index {
  @State isDownloading: boolean = false;
  @State hintStr: string = '点击开始下载';

  build() {
    Column({ space: 20 }) {
      Button(this.isDownloading ? '下载中' : '点击下载')
        .accessibilityLevel('yes')
        .accessibilityTextHint(this.hintStr)
        .onClick(() => {
          this.isDownloading = !this.isDownloading;
          this.hintStr = this.isDownloading ? '状态变为下载中' : '状态变为暂停下载';
        })
      TextInput({ placeholder: '请输入手机号码' })
        .accessibilityLevel('yes')
        .accessibilityTextHint('请输入11位手机号码')
        .width('80%')
      Text('按照按钮类型播报')
        .accessibilityLevel('yes')
        .accessibilityRole(AccessibilityRoleType.BUTTON)
        .accessibilityTextHint('屏幕朗读播报时，该组件将按照按钮类型进行播报')
        .fontSize(30)
    }
    .height('100%')
    .width('100%')
  }
}

示例5（设置无障碍屏幕朗读滚动和焦点绿框绘制）

该示例主要演示accessibilityScrollTriggerable设置无障碍节点是否支持屏幕朗读滚动、accessibilityFocusDrawLevel设置无障碍焦点绿框的绘制层级和accessibilityUseSamePage设置UIExtensionComponent的accessibilityUseSamePage属性。

// xxx.ets
import { ComponentContent } from '@kit.ArkUI';

class Params {
}
@Builder
function LoadingBuilder(params: Params) {
  Column() {
    LoadingProgress()
      .color('#4A90E2')
  }
}
@Entry
@Component
struct Index {
  private contentNode = new ComponentContent(this.getUIContext(), wrapBuilder(LoadingBuilder), new Params);

  build() {
    Row() {
      List() {
        ListItem() {
          Column() {
            Stack() {
              Column() {
                Text('文本1')
                  .fontSize(18)
                  .fontColor('#2D2D2D')
                  .fontWeight(FontWeight.Medium)
                Text('文本1')
                  .fontSize(18)
                  .fontColor('#2D2D2D')
                  .fontWeight(FontWeight.Medium)
                  .accessibilityFocusDrawLevel(FocusDrawLevel.TOP)
              }
              .padding({ top: 8, bottom: 8 })
              Column() {
                Text('文本2')
                  .fontSize(18)
                  .fontColor('#FFFFFF')
                  .fontWeight(FontWeight.Medium)
                Text('文本2')
                  .fontSize(18)
                  .fontColor('#FFFFFF')
                  .fontWeight(FontWeight.Medium)
              }
              .backgroundColor('#4A90E2')
              .padding({ left: 12, right: 12, top: 10, bottom: 10 })
              .borderRadius(6)
            }
            .width('100%')
            .margin({ top: 10, bottom: 10 })
            Column() {
              UIExtensionComponent({
                bundleName: 'com.example.provide',
                abilityName: 'EmptyUIExtensionAbility',
                parameters: {
                  'ability.want.params.uiExtensionType': 'sys/commonUI'
                }
              },
                {
                  placeholder: this.contentNode,
                  dpiFollowStrategy: DpiFollowStrategy.FOLLOW_UI_EXTENSION_ABILITY_DPI
                })
                .onReceive((err) => {
                  console.error('onReceive' + JSON.stringify(err));
                })
                .onError((err) => {
                  console.error('onError code :' + err.code + ', name: ' + err.name + ', msg: ' + err.message);
                  console.error('onError' + JSON.stringify(err));
                })
                .accessibilityUseSamePage(AccessibilitySamePageMode.FULL_SILENT)
                .width('50%')
                .height('50%')
                .backgroundColor('#F0F0F0')
                .borderRadius(8)
                .borderWidth(1)
                .borderColor('#D9D9D9')
            }
            .width('100%')
            .height('100%')
            .margin({ top: 50 })
            .accessibilityText($r('app.string.app_name'))
            .accessibilityDescription($r('app.string.module_desc'))
            Column() {
              Text('文本4')
                .fontSize(18)
                .fontWeight(FontWeight.Medium)
            }
            .margin({ top: 15 })
          }
          .width('100%')
        }
      }
      .accessibilityScrollTriggerable(false)
      .width('100%')
    }
    .height('100%')
    .backgroundColor('#F7F9FC')
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙图像AI分析错误码

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙弹出框 (Dialog)

harmony 鸿蒙DialogV2