Accessibility Label — 它是什么，基础知识以及如何为 iOS 和 Android 使用

iOS：accessibilityLabel 属性

在 iOS 中，accessibilityLabel被所有 UIView 从 UIAccessibility 协议继承。如果元素包含文本（带 title 的 UIButton、带 text 的 UILabel），Label 会自动设置为该文本。对于 UIImageView、自定义控件和容器，需要手动设置 Label。

自定义表格单元格的示例：

class CustomTableViewCell: UITableViewCell {
    let titleLabel = UILabel()
    let priceLabel = UILabel()

    override func awakeFromNib() {
        super.awakeFromNib()
        self.isAccessibilityElement = true
        self.accessibilityLabel =
            "\(titleLabel.text ?? "") - \(priceLabel.text ?? "")"
    }
}

对于自定义 UIView，可以覆写 accessibilityLabel 的 getter：

class RatingView: UIView {
    var rating: Int = 5

    override var accessibilityLabel: String? {
        get { return "评分：\(rating) / 5" }
        set {}
    }
}

Apple HIG, 2024 建议：如果元素由多个子元素组成（例如带有名称和价格的产品卡片），请将它们组合成一个具有复合 Label 的无障碍元素。在父元素上设置 isAccessibilityElement = true，在子元素上设置 false。

NSAttributedString 和 accessibilityLabel

如果 UILabel 使用 NSAttributedString，accessibilityLabel 默认等于 .string（纯文本）。如果需要传递语义上不同的值（例如，图标符号应读作“星星”而非符号 ★），请显式设置 accessibilityLabel。VoiceOver 无法有意义地读取 Unicode 符号。

Android：通过 contentDescription 的 Label

在 Android 中，contentDescription担任 ImageView、ImageButton 和自定义 View 的 Label。对于内置文本的 TextView 和 Button，无需设置 contentDescription——TalkBack 会自动读取文本。

通过 Kotlin 进行编程设置：

binding.iconStar.contentDescription = "商品在收藏夹中"

// 对于具有多个元素的自定义视图
binding.customCard.setContentDescription(
    "\(title) 金额 \(price)")

在 XML 中用于装饰性元素：

<ImageView
    android:contentDescription="@null"
    android:src="@drawable/divider"
    android:importantForAccessibility="no" />

importantForAccessibility = "no"属性完全将元素从无障碍树中排除。在 iOS 中，它的等效属性是 isAccessibilityElement = false。

Compose：semantics 和 contentDescription

在 Jetpack Compose 中，Label 通过semantics修饰符设置：

Image(
    painter = painterResource(R.drawable.ic_search),
    contentDescription = "商品搜索",
    modifier = Modifier.semantics {
        contentDescription = "商品搜索"
    }
)

在 Compose 中，contentDescription 是 Image 的必须参数——没有它，代码将无法编译（警告）。这通过 API 设计强制提升了无障碍。

Label 和 Hint：作用的区别

Accessibility Label回答“这是什么元素？”的问题。Hint（iOS 中的 accessibilityHint，Android 中 contentDescription 中的附加文本）——“交互时会发生什么？”。VoiceOver 会顺序念出它们：先 Label，后 Hint。

删除按钮的示例：

• Label：“删除”
• Hint：“将不可撤销地删除所选照片”
• VoiceOver：“删除。将不可撤销地删除所选照片”

根据 Deque University, 2024，Label 和 Hint 的正确分离使 VoiceOver 用户的任务完成率提高了 28%。有认知障碍的用户尤其依赖 Hint：如果没有说明就冒险按下“删除”，40%的用户会放弃操作。

何时不需要 Hint

• 具有直觉可懂操作的元素（“返回”、“关闭”——Label 足够）
• Label 已经描述了结果（“发送消息”——动词在名称本身）
• 系统控件（UISwitch、带系统类型的 UIButton）——其行为是标准的

实践中的错误：用 Label 代替 Hint

常见错误：在 Label 中写“删除按钮”而非“删除”。元素类型（按钮）由 VoiceOver 通过 trait 自动添加。结果，用户听到：“删除按钮，按钮”——重复。正确的 Label：“删除”，Hint：“将删除所选照片”

本地化和最佳实践

标签的本地化是必须的——通过标准机制实现：iOS 中的 NSLocalizedString，Android 中的 @string/ 字符串资源。切勿在没有本地化的情况下用英语拼接方式设置 Label。

基于 W3C WCAG 2.2 的良好 Label 规则：

• 以关键词开头——“产品搜索”，而非“产品搜索的字段”
• 不要包含“按钮”、“字段”、“图像”等词——角色会自动添加
• 使用目标受众能理解的自然语言
• 避免缩写（除了常见的：“个”、“公斤”）——屏幕读取器会按字面读取
• 对于输入元素，添加示例：“电子邮件（example@domain.com）”

品牌内 Label 的一致性

在应用程序中为 Label 使用统一的词汇表。如果一个屏幕上写着“收藏”，而另一个屏幕上写着“书签”，用户就会困惑。创建一个无障碍术语表——与设计师和本地化人员协调。

表单元素的 Label

对于输入字段（UITextField、EditText），Label 应与填充文本或字段标题一致。但是填充文本在输入文本后常常会消失。使用 accessibilityLabel 作为永久名称，使用 accessibilityValue 作为字段当前内容——这是 WCAG 4.1.2 标准。解决方案：静态设置 accessibilityLabel（等于字段标题），动态设置 accessibilityValue（等于输入的文本）。在 iOS 中这是自动的，但对于自定义字段——需要通过覆写 accessibilityValue 手动实现。检查 VoiceOver 是否读取“电子邮件，example@domain.com，文本字段”而非“，文本字段”。

如何测试无障碍标签

自动化测试是保证 Label 在所有屏幕上正确性的唯一方法。iOS 提供了 XCUIApplication，可以访问 .label，Android 则提供 AccessibilityCheckRule 和 setContentDescription。

iOS 测试示例：

func testLabelsAreUnique() {
    let app = XCUIApplication()
    app.launch()
    let allButtons = app.buttons.allElementsBoundByIndex
    let labels = allButtons.compactMap { $0.label }
    let uniqueLabels = Set(labels)
    XCTAssertEqual(labels.count, uniqueLabels.count,
        "发现重复的 Label")
}

使用 Espresso 的 Android 测试示例：

@Test
fun testButtonHasAccessibilityLabel() {
    onView(withId(R.id.btnSubmit))
        .check(matches(
            withContentDescription(containsString("发送"))
        ))
}

手动测试：开启 VoiceOver（iOS）或 TalkBack（Android），然后用手指向右滑动遍历屏幕上的所有元素。每个元素应收到有意义的声明。如果只听到“按钮”或“图像”——Label 缺失。

VoiceOver 转盘和快速导航

设置 Label 后，VoiceOver 用户可以使用转盘进行快速导航：“按钮”、“标题”、“链接”等模式。如果 Label 设置正确，VoiceOver 将元素包含在相应的转盘模式中。检查所有按钮是否在“按钮”模式中可见，所有标题是否在“标题”模式中可见。

Label 还影响 VoiceOver 的搜索功能。用户可以在搜索模式中输入词语，VoiceOver 将把聚焦移到具有匹配 Label 的元素上。因此，Label 应包含用户查找元素时使用的关键词。

集成到 CI/CD 管道

将 Label 检查添加到管道。在 iOS 上，使用带 fastlane scan 的XCUITest。在 Android 上，使用Accessibility Test Framework，其 AccessibilityCheckRule 规则可检测空的 contentDescription。这可以避免在合并新屏幕时产生回退。