Compose 中的语义

一个组合 描述了您的应用的 UI，并且是通过运行可组合项生成的。组合是一个树状结构，它由描述您的 UI 的可组合项组成。

除了组合之外，还存在一个并行的树，称为语义树。这棵树以另一种方式描述您的 UI，这种方式对于 辅助功能 服务和 测试 框架来说是可以理解的。辅助功能服务使用该树向有特定需求的用户描述应用。测试框架使用该树与您的应用交互并对其进行断言。语义树不包含有关如何绘制可组合项的信息，但它包含有关可组合项的语义含义的信息。

如果您的应用由 Compose 基础库和 Material 库中的可组合项和修饰符组成，则会自动为您填充和生成语义树。但是，当您添加自定义低级可组合项时，您必须手动提供其语义。也可能存在树无法正确或完整地表示屏幕上元素含义的情况，在这种情况下，您可以调整树。

例如，考虑这个自定义日历可组合项

在此示例中，整个日历作为单个低级可组合项实现，使用 Layout 可组合项并直接绘制到 Canvas 上。如果您不执行其他操作，辅助功能服务将无法接收有关可组合项内容和用户在日历中选择的足够信息。例如，如果用户点击包含 17 的日期，辅助功能框架只会收到整个日历控件的描述信息。在这种情况下，TalkBack 辅助功能服务将宣布“日历”或仅稍微好一点的“四月日历”，用户会想知道选择了哪一天。为了使此可组合项更易于访问，您需要手动添加语义信息。

语义属性

UI 树中具有某些语义含义的所有节点在语义树中都有一个并行节点。语义树中的节点包含那些传达相应可组合项含义的属性。例如，Text 可组合项包含一个语义属性 text，因为这是该可组合项的含义。一个 Icon 包含一个 contentDescription 属性（如果由开发者设置），该属性以文本形式传达 Icon 的含义。构建在 Compose 基础库 之上的可组合项和修饰符已经为您设置了相关属性。或者，您可以使用 semantics 和 clearAndSetSemantics 修饰符自己设置或覆盖属性。例如，向节点添加 自定义辅助功能操作，为可切换元素提供替代的 状态描述，或指示某个文本可组合项应被视为 标题。

要可视化语义树，请使用 布局检查器 工具或使用 printToLog() 方法在测试中。这会将当前语义树打印到 Logcat 中。

class MyComposeTest {

    @get:Rule
    val composeTestRule = createComposeRule()

    @Test
    fun MyTest() {
        // Start the app
        composeTestRule.setContent {
            MyTheme {
                Text("Hello world!")
            }
        }
        // Log the full semantics tree
        composeTestRule.onRoot().printToLog("MY TAG")
    }
}
SemanticsSnippets.kt

此测试的输出将是

    Printing with useUnmergedTree = 'false'
    Node #1 at (l=0.0, t=63.0, r=221.0, b=120.0)px
     |-Node #2 at (l=0.0, t=63.0, r=221.0, b=120.0)px
       Text = '[Hello world!]'
       Actions = [GetTextLayoutResult]

考虑语义属性如何传达可组合项的含义。考虑一个 Switch。这就是它在用户看来是什么样子

要描述此元素的含义，您可以说以下内容：“这是一个 Switch，它是一个处于'开启'状态的可切换元素。您可以点击它与之交互。”

这正是语义属性的用途。此 Switch 元素的语义节点包含以下属性，如布局检查器所示

Role 指示元素的类型。StateDescription 描述了如何引用“开启”状态。默认情况下，这是“开启”一词的本地化版本，但可以根据上下文使其更具体（例如，“已启用”）。ToggleableState 是 Switch 的当前状态。OnClick 属性引用用于与该元素交互的方法。有关语义属性的完整列表，请查看 SemanticsProperties 对象。有关可能的辅助功能操作的完整列表，请查看 SemanticsActions 对象。

跟踪应用中每个可组合项的语义属性可以解锁许多强大的可能性。一些例子

• Talkback 使用这些属性大声朗读屏幕上显示的内容，并允许用户流畅地与之交互。对于 Switch 可组合项，Talkback 可能会说：“开启；Switch；双击切换”。用户可以双击屏幕将 Switch 切换到关闭状态。
• 测试框架使用这些属性查找节点、与之交互并进行断言。Switch 的示例测试可能是

  val mySwitch = SemanticsMatcher.expectValue(
      SemanticsProperties.Role, Role.Switch
  )
  composeTestRule.onNode(mySwitch)
      .performClick()
      .assertIsOff()
  SemanticsSnippets.kt

合并和未合并的语义树

如前所述，UI 树中的每个可组合项可能都设置了零个或多个语义属性。当可组合项未设置任何语义属性时，它不会包含在语义树中。这样，语义树仅包含实际包含语义含义的节点。但是，有时为了传达屏幕上显示内容的正确含义，将某些节点的子树合并并将其视为一个整体也很有用。这样，您可以将一组节点作为一个整体进行推理，而不是分别处理每个子节点。根据经验，此树中的每个节点都表示使用辅助功能服务时的可聚焦元素。

此类可组合项的一个示例是 Button。您可以将按钮视为单个元素，即使它可能包含多个子节点

Button(onClick = { /*TODO*/ }) {
    Icon(
        imageVector = Icons.Filled.Favorite,
        contentDescription = null
    )
    Spacer(Modifier.size(ButtonDefaults.IconSpacing))
    Text("Like")
}
SemanticsSnippets.kt

在语义树中，按钮的后代的属性会合并，并且按钮在树中显示为单个叶节点

可组合项和修饰符可以通过调用 Modifier.semantics (mergeDescendants = true) {} 来指示它们希望合并其后代的语义属性。将此属性设置为 true 表示应合并语义属性。在 Button 示例中，Button 可组合项在内部使用包含此 semantics 修饰符的 clickable 修饰符。因此，按钮的后代节点将被合并。阅读辅助功能文档，了解何时应在可组合项中 更改合并行为。

Foundation 和 Material Compose 库中的多个修饰符和可组合项都设置了此属性。例如，clickable 和 toggleable 修饰符将自动合并其后代。此外，ListItem 可组合项也将合并其后代。

检查树

语义树实际上是两棵不同的树。有一棵合并的语义树，当 mergeDescendants 设置为 true 时，它会合并后代节点。还有一棵未合并的语义树，它不应用合并，而是保持每个节点完整。辅助功能服务使用未合并的树并应用其自己的合并算法，同时考虑 mergeDescendants 属性。测试框架默认使用合并的树。

您可以使用 printToLog() 方法检查这两棵树。默认情况下，以及在前面的示例中，会记录合并的树。要改为打印未合并的树，请将 onRoot() 匹配器的 useUnmergedTree 参数设置为 true

composeTestRule.onRoot(useUnmergedTree = true).printToLog("MY TAG")
SemanticsSnippets.kt

布局检查器允许您通过在视图过滤器中选择首选视图来显示合并的和未合并的语义树。

对于树中的每个节点，布局检查器都会在属性面板中显示合并的语义和该节点上设置的语义。

默认情况下，测试框架中的匹配器使用合并的语义树。这就是为什么您可以通过匹配其中显示的文本与 Button 进行交互的原因。

composeTestRule.onNodeWithText("Like").performClick()
SemanticsSnippets.kt

通过将匹配器的 useUnmergedTree 参数设置为 true 来覆盖此行为，就像 onRoot 匹配器一样。

合并行为

当可组合项指示其后代应被合并时，此合并是如何精确发生的？

每个语义属性都有一个定义的合并策略。例如，ContentDescription 属性将所有后代 ContentDescription 值添加到列表中。通过检查其在 SemanticsProperties.kt 中的 mergePolicy 实现来检查语义属性的合并策略。属性可以采用父级或子级值、将值合并到列表或字符串中、完全不允许合并并改为抛出异常，或任何其他自定义合并策略。

需要注意的是，本身已设置 mergeDescendants = true 的后代不包含在合并中。让我们看一个例子。

这是一个可点击的列表项。当用户按下该行时，应用会导航到文章详情页面，用户可以在该页面阅读文章。在列表项内，有一个按钮可以将文章添加书签，该按钮形成一个嵌套的可点击元素，因此该按钮在合并的树中单独显示。该行中的其余内容已合并。

调整语义树

如前所述，您可以覆盖或清除某些语义属性或更改树的合并行为。当您创建自己的自定义组件时，这一点尤其重要。如果不设置正确的属性和合并行为，您的应用可能无法访问，并且测试的行为可能与您的预期不同。要了解有关应调整语义树的一些常见用例的更多信息，请阅读 辅助功能文档。如果您想了解有关测试的更多信息，请查看 测试指南。

其他资源

• 辅助功能: 所有 Android 应用开发中常见的核心概念和技术
• 构建可访问的应用: 使您的应用更易访问可以采取的关键步骤
• 改善应用辅助功能的原则: 在努力使您的应用更易访问时需要牢记的关键原则
• 辅助功能测试: Android 辅助功能的测试原则和工具