ItemContainer 控件模式

  • 项目

介绍实现 IItemContainerProvider 的准则和约定，包括有关方法的信息。 ItemContainer 控件模式用于支持项虚拟化。

包含大量子项的控件可以使用虚拟化有效地管理这些项。 通过虚拟化，控件在任何给定时间仅保留一部分项的内存中的完整信息。 通常，子集仅包括用户当前可见的那些项。 有关剩余虚拟化项的完整信息保存在存储中，并加载到内存中，或实现，因为控件需要它，例如，当新项对用户可见时。

例如，下图显示了包含数千个虚拟化项的列表框。 由于 控件仅维护当前可见子项的完整信息，因此提供程序只能公开项 100-127 的 Microsoft UI 自动化元素。

显示列表框中已虚拟化和未虚拟化的项目的关系图

使用虚拟化的控件是一个挑战，因为只有实现 (去虚拟化) 项才完全作为UI 自动化树中的UI 自动化元素可用。 虚拟化项不存在于树中，因此有关这些项的信息不可用。

为了提供有关虚拟化项的信息，提供程序实现 ItemContainer 控件模式，该模式公开 IItemContainerProvider 接口。 FindItemByProperty 方法根据特定属性（如 Name、AutomationId 或 IsSelected）的值查找子项。 如果某个项已虚拟化，FindItemByProperty 将检索项的UI 自动化占位符元素。 占位符元素是仅支持 VirtualizedItem 控件模式的 IRawElementProviderSimple 接口的实现。

IVirtualizedItemProvider：：Realize 方法使客户端能够请求实现虚拟化项，从而公开项的完整UI 自动化元素，以便所有必需的属性和模式都可用。

尽管 ItemContainer 控制模式的主要用途是支持虚拟化容器方案，但无论容器是否使用虚拟化，它都可以由按名称检索子项的任何容器实现。

本主题包含以下各节：

实现准则和约定

实现 ItemContainer 控件模式时，请注意以下准则和约定：

  • 任何可以包含虚拟化项的控件都必须支持 ItemContainer 控件模式。 任何支持基于属性值检索项的容器都可以支持此模式，而不管容器是否使用虚拟化。
  • 虚拟化容器时，其他控件模式（如“选择”、“表”和“网格”）可能会受到影响。 例如， ISelectionProvider：：GetSelection 方法可能仅支持视区中的元素，或仅支持当前未虚拟化的选定元素。
  • 滚动控件模式应不受虚拟化影响。
  • 没有项计数或索引信息可用于虚拟化项。 如有必要，虚拟化控件可以使用 DescribedBy 或 ItemStatus 属性来提供此信息。
  • 控件开发人员应记录和发布受虚拟化使用影响的所有UI 自动化属性和控件模式的详细信息。 尽管 ItemContainer 和 VirtualizedItem 控件模式提供基本支持，但它们可能不支持某些虚拟化行为。

以下准则和要求适用于 IItemContainerProvider：：FindItemByProperty 方法。

  • 虽然不是必需的，但 Microsoft 强烈建议 FindItemByProperty 支持 Name、 AutomationId 和 IsSelected 属性。
  • 如果需要遍历多个对象来查找匹配的对象，FindItemByProperty 可能会很慢。
  • 可以重复调用 FindItemByProperty 以按顺序查找项。 只要每个项只返回一次，这些项就可以按任意顺序排列。
  • 可以实现 FindItemByProperty，以便仅查找显示在UI 自动化树的控件或内容视图中的那些元素。 可以跳过仅出现在原始视图中的元素，以避免检索仅表示用户“项”部分的多个元素。
  • 当搜索条件与虚拟化项匹配时，提供程序可以返回支持 VirtualizedItem 控件模式的占位符元素。 以下准则适用于占位符元素：
    • 检索虚拟化项的占位符元素不得导致 UI 更改。
    • 占位符元素必须是其他子元素的对等项， (需要) 结构更改事件。
    • 如果可能，提供程序可以创建完全自动化元素，而不是占位符。
  • 当搜索条件与非虚拟化元素匹配时，提供程序必须返回实际元素，而不是占位符。
  • 如果未找到任何项， IItemContainerProvider：：FindItemByProperty 应将 pFound 参数设置为 NULL 并返回 S_OK。
  • 当 propertyId 参数为 0 时，提供程序应在 pStartAfter 之后返回下一项。
  • 如果 pStartAfter 参数为 NULL 且 propertyId 为 0，则提供程序应返回容器中的第一项。
  • 当 propertyId 参数为 0 时，值参数将被忽略。

以下准则和要求适用于UI 自动化树中虚拟化项的占位符元素。

  • 尽管建议提供程序支持占位符元素的更多属性和控件模式，但只需要 VirtualizedItem 控件模式。
  • 再次调用 IItemContainerProvider：：FindItemByProperty 时，提供程序可能会使以前的占位符元素失效。 (如果客户端需要实现占位符元素，应立即实现;否则，如果再次调用 FindItemByProperty 或视区因任何原因而更改，则元素可能会失效。)
  • 滚动或调整大小等 UI 操作可能会导致容器的视区发生更改，并且一组新的子项变为可见。 在这种情况下，以前检索的占位符元素在UI 自动化树中可能不可用。
  • 提供程序不应虚拟化容器对象的视区中屏幕上可用的 UI 元素。

IItemContainerProvider 的必需成员

实现 IItemContainerProvider 接口需要以下方法。

必需的成员 成员类型 说明
FindItemByProperty 方法 无

 

ItemContainer 控件模式没有关联的属性或事件。

控件类型及其支持的控件模式

UI 自动化控件模式概述

UI 自动化树概述

VirtualizedItem 控件模式