Automation 元素属性标识符
本主题介绍标识 Microsoft UI 自动化元素的属性的命名常量。
| 常量/值 | 说明 |
|---|---|
|
标识 AcceleratorKey 属性，该属性是包含快捷键的字符串 (也称为快捷键) 自动化元素的组合。 快捷键组合调用操作。 例如，CTRL+O 通常用于调用“打开文件”公共对话框。 具有 AcceleratorKey 属性的自动化元素可以为等效于快捷方式命令的操作实现 Invoke 控件模式。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 AccessKey 属性，该属性是包含自动化元素的访问键字符的字符串。 访问键 (有时称为助记键) 是菜单、菜单项或控件标签（如按钮）的文本中的字符，用于激活关联的菜单功能。 例如，若要打开访问键通常为 F 的“文件”菜单，用户可按 Alt+F。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 AnnotationObjects 属性，该属性是文档中批注对象（如注释、页眉、页脚等）的列表。 变量类型： VT_I4 | VT_ARRAY 默认值：空数组 |
|
标识 AnnotationTypes 属性，该属性是文档中批注类型（如注释、页眉、页脚等）的列表。 变量类型： VT_I4 | VT_ARRAY 默认值：空数组 |
|
标识 AriaProperties 属性，该属性是一个格式化字符串，其中包含自动化元素的可访问富 Internet 应用程序 (ARIA) 属性信息。 有关将 ARIA 状态和属性映射到 UI 自动化属性和函数的详细信息，请参阅 适用于 W3C 可访问的富 Internet 应用程序的 UI 自动化规范。 AriaProperties 是名称/值对的集合，其分隔符 = (等于) 和 ; (分号) ，例如“checked=true;disabled=false”。 当 \ 这些分隔符或出现在值中时， (反斜杠) 用作转义字符 \ 。 出于安全性和其他原因，此属性的提供程序实现可以采取措施来验证原始 ARIA 属性;但是，这不是必需的。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 AriaRole 属性，该属性是包含自动化元素的可访问富 Internet 应用程序 (ARIA) 角色信息的字符串。 有关将 ARIA 角色映射到 UI 自动化控件类型的详细信息，请参阅 适用于 W3C 可访问的富 Internet 应用程序的 UI 自动化规范。 注意：
|
|
标识 AutomationId 属性，该属性是包含自动化元素的 UI 自动化标识符 (ID) 的字符串。 如果可用，则元素的 AutomationId 在应用程序的任何实例中都必须相同，而不考虑本地语言。 值在同级元素中应是唯一的，但不一定在整个桌面上是唯一的。 例如，一个应用程序的多个实例或 Microsoft Windows 资源管理器中的多个文件夹视图可以包含具有相同 AutomationId 属性的元素，例如“SystemMenuBar”。 尽管始终建议支持 AutomationId 以提供更好的自动测试支持，但此属性不是必需的。 在支持的情况下， AutomationId 可用于创建不考虑 UI 语言运行的测试自动化脚本。 客户端不应对其他应用程序公开的 AutomationId 值做出假设。 不保证 AutomationId 在应用程序的不同版本或内部版本中保持稳定。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 BoundingRectangle 属性，该属性指定完全包围自动化元素的矩形的坐标。 矩形以物理屏幕坐标表示。 如果 UI 项的形状或可单击区域不规则，或者项目被其他 UI 元素遮盖，则它可以包含不可单击的点。 变量类型： VT_R8 | VT_ARRAY 默认值：[0，0，0，0] 注意：
|
|
标识 CenterPoint 属性，该属性指定自动化元素的中心 X 和 Y 点坐标。 坐标空间是提供程序在逻辑上认为页面的空间。 变量类型： VT_R8 | VT_ARRAY 默认值： VT_EMPTY |
|
标识 ClassName 属性，该属性是一个字符串，其中包含控件开发人员分配的自动化元素的类名。 类名取决于 UI 自动化提供程序的实现，因此并不总是采用标准格式。 但是，如果类名已知，则可用于验证应用程序是否正在使用预期的自动化元素。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 ClickablePoint 属性，该属性是可单击的自动化元素上的一个点。 如果元素被另一个窗口完全或部分遮挡，则无法单击该元素。 变量类型： VT_R8 | VT_ARRAY 默认值： VT_EMPTY |
|
标识 ControllerFor 属性，该属性是由支持此属性的自动化元素操作的自动化元素数组。 当自动化元素影响应用程序 UI 或桌面的一个或多个段时，使用 ControllerFor;否则，很难将控件操作的影响与 UI 元素相关联。 此标识符通常用于 自动建议辅助功能。 提供程序的变体类型： VT_UNKNOWN | VT_ARRAY 客户端的变体类型： VT_UNKNOWN (IUIAutomationElementArray ) 默认值：空数组 |
|
标识 ControlType 属性，该属性是标识自动化元素类型的类。 ControlType 通过已知的 UI 控件基元（如按钮或检查框）定义 UI 元素的特征。 变量类型： VT_I4 默认值： UIA_CustomControlTypeId 注意：
|
|
标识 Culture 属性，该属性包含自动化元素的区域设置标识符 (例如0x0409“en-US”或英语 (美国) ) 。每个区域设置都有一个唯一标识符，一个由语言标识符和排序顺序标识符组成的 32 位值。 区域设置标识符是标准的国际数字缩写，具有唯一地标识已安装的操作系统定义的区域设置之一所需的组件。 有关详细信息，请参阅语言标识符常量和字符串。 此属性可能基于每个控件存在，但通常仅在应用程序级别可用。 变量类型： VT_I4 默认值：0 |
|
标识 DescribedBy 属性，该属性是提供有关自动化元素的详细信息的元素数组。 当应用程序 UI 的另一段解释自动化元素时，使用 DescribedBy。 例如， 属性可以从复杂的自定义列表对象中指向“85 个组中的 2，529 个项目，已选择 10 个项目”的文本元素。 DescribedBy 属性可以提供对可能已经提供描述 UI 元素的有用最终用户信息的 UI 元素的快速访问，而不是使用对象模型来消化类似信息。 提供程序的变体类型： VT_UNKNOWN | VT_ARRAY 客户端的变体类型： VT_UNKNOWN (IUIAutomationElementArray) 默认值：空数组 |
|
标识 FillColor 属性，该属性指定用于填充自动化元素的颜色。 此属性指定为 COLORREF，这是用于指定 RGB 或 RGBA 颜色的 32 位值。 变量类型： VT_I4 默认值：0 |
|
标识 FillType 属性，该属性指定用于填充自动化元素的图案，例如无、颜色、渐变、图片、图案等。 变量类型： VT_I4 默认值：0 |
|
标识 FlowFrom 属性，该属性是自动化元素的数组，建议当前自动化元素之前的读取顺序。 从 Windows 8 开始受支持。 当自动化元素不以用户感知到的相同读取顺序公开或结构化时， FlowFrom 属性指定读取顺序。 虽然 FlowFrom 属性可以指定多个前面的元素，但它通常只包含读取顺序中的上一个元素。 提供程序的变体类型： VT_UNKNOWN | VT_ARRAY 客户端的变体类型： VT_UNKNOWN (IUIAutomationElementArray) 默认值：空数组 |
|
标识 FlowTo 属性，该属性是自动化元素的数组，建议当前自动化元素之后的读取顺序。 当自动化元素不以用户感知到的相同读取顺序公开或结构化时， FlowTo 属性指定读取顺序。 虽然 FlowsTo 属性可以指定多个后续元素，但它通常只包含读取顺序中的下一个元素。 提供程序的变体类型： VT_UNKNOWN | VT_ARRAY 客户端的变体类型： VT_UNKNOWN (IUIAutomationElementArray) 默认值：空数组 |
|
标识 FrameworkId 属性，该属性是一个字符串，其中包含自动化元素所属的基础 UI 框架的名称。 FrameworkId 使客户端应用程序能够根据特定的 UI 框架以不同的方式处理自动化元素。 属性值的示例包括“Win32”、“WinForm”和“DirectUI”。 变量类型： VT_BSTR 默认值：空字符串 |
|
FullDescription 属性公开一个本地化字符串，该字符串可以包含元素的扩展说明文本。 FullDescription 可以包含比元素 名称更完整的元素说明。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 HasKeyboardFocus 属性，该属性是一个布尔值，指示自动化元素是否具有键盘焦点。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 HeadingLevel 属性，该属性指示 UI 自动化元素的标题级别。 变量类型： VT_I4 默认值： HeadingLevel_None |
|
标识 HelpText 属性，该属性是与自动化元素关联的帮助文本字符串。 当占位符文本出现在编辑控件或列表控件中时，可以支持 HelpText 属性。 例如，“在此处键入用于搜索的文本”是编辑控件的 HelpText 属性的候选项，该控件将文本置于用户的实际输入之前。 但是，对于编辑控件的名称属性来说，这还不够。 如果 支持 HelpText ，则字符串必须与应用程序 UI 语言或操作系统默认 UI 语言匹配。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 IsContentElement 属性，该属性是一个布尔值，指定元素是否显示在自动化元素树的内容视图中。 有关详细信息，请参阅 UI 自动化树概述。 注意：
|
|
标识 IsControlElement 属性，该属性是一个布尔值，指定元素是否显示在自动化元素树的控件视图中。 有关详细信息，请参阅 UI 自动化树概述。 变体类型： VT_BOOL 默认值： TRUE |
|
标识 IsDataValidForForm 属性，该属性是一个布尔值，指示输入的值或所选值对于与自动化元素关联的表单规则是否有效。 例如，如果用户为需要 5 或 9 位数字的邮政编码字段输入了“425-555-5555”，则可以将 IsDataValidForForm 属性设置为 FALSE 以指示数据无效。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 IsDialog 属性，该属性是一个布尔值，指示自动化元素是否为对话框窗口。 例如，辅助技术（如屏幕阅读器）通常会说出对话框的标题、对话框中的焦点控件，然后将对话框的内容说到焦点控件 (“是否要在关闭之前保存更改”) 。 对于标准窗口，屏幕阅读器通常说出窗口标题，后跟焦点控件。 IsDialog 属性可以设置为 TRUE，以指示客户端应用程序应将 元素视为对话框窗口。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 IsEnabled 属性，该属性是一个布尔值，指示自动化元素引用的 UI 项是否已启用并且可以与之交互。 当控件的启用状态为 FALSE 时，假定子控件也未启用。 当父控件的状态发生更改时，客户端不应期望子元素发生属性更改事件。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 IsKeyboardFocusable 属性，该属性是一个布尔值，指示自动化元素是否可以接受键盘焦点。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 IsOffscreen 属性，该属性是一个布尔值，指示自动化元素是否完全滚动出视图 (例如，容器对象视区外的列表框中的项) 或折叠出视图 (例如树视图或菜单中的项， 或在最小化的窗口中) 。 如果元素具有可单击的点，该点可能导致它接收焦点，则元素被视为在屏幕上，而元素的一部分位于屏幕外。 属性的值不受其他窗口的遮挡或元素在特定监视器上是否可见的影响。 如果 IsOffscreen 属性为 TRUE，则 UI 元素在屏幕外滚动或折叠。 元素暂时隐藏，但仍保留在最终用户的感知中，并继续包含在 UI 模型中。 可以通过滚动、单击下拉列表等方式使对象重新进入视图。 最终用户根本无法察觉或“以编程方式隐藏”的对象 (例如，已关闭的对话框，但基础对象仍由应用程序缓存，) 首先不应位于自动化元素树中 (，而不是将 IsOffscreen 的状态设置为 TRUE) 。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 IsPassword 属性，该属性是一个布尔值，指示自动化元素是包含受保护的内容还是密码。 当 IsPassword 属性为 TRUE 且元素具有键盘焦点时，客户端应用程序应禁用键盘回显或键盘输入反馈，这可能会公开用户的受保护信息。 尝试访问受保护元素的 Value 属性 (编辑控件) 可能会导致出错。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 IsPeripheral 属性，该属性是一个布尔值，指示自动化元素是否表示外围 UI。 外围 UI 显示并支持用户交互，但显示时不具有键盘焦点。 外围 UI 的示例包括弹出窗口、浮出控件、上下文菜单或浮动通知。 从 Windows 8.1 开始支持。 当 IsPeripheral 属性为 TRUE 时，客户端应用程序不能假定焦点是由 元素获取的，即使它当前是键盘交互的。 此属性与以下控件类型相关：
默认值： FALSE |
|
标识 IsRequiredForForm 属性，该属性是一个布尔值，指示是否需要在窗体上填写自动化元素。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 ItemStatus 属性，该属性是描述自动化元素的项状态的文本字符串。 ItemStatus 使客户端能够确定元素是否正在传达有关项的状态以及状态是什么。 例如，与消息应用程序中的联系人关联的项目可能是“忙碌”或“已连接”。 如果支持 ItemStatus ，则字符串必须与应用程序 UI 语言或操作系统默认 UI 语言匹配。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 ItemType 属性，该属性是描述自动化元素类型的文本字符串。 ItemType 用于获取有关列表、树视图或数据网格中的项的信息。 例如，文件目录视图中的项可能是“文档文件”或“文件夹”。 如果 支持 ItemType ，则字符串必须与应用程序 UI 语言或操作系统默认 UI 语言匹配。 变量类型： VT_BSTR 默认值：空字符串 |
|
标识 LabeledBy 属性，该属性是包含此元素的文本标签的自动化元素。 例如，此属性可用于检索组合框的静态文本标签。 变量类型： VT_UNKNOWN 默认值： NULL |
|
标识 LandmarkType 属性，该属性是与元素关联的 陆标类型标识符 。 LandmarkType 属性描述表示一组元素的元素。 例如，搜索标志可以表示一组用于搜索的相关控件。 如果使用 UIA_CustomLandmarkTypeId ，则需要 UIA_LocalizedLandmarkTypePropertyId 来描述自定义陆标。 变量类型： VT_I4 默认值：0 |
|
标识 Level 属性，该属性是与自动化元素关联的从 1 开始的整数。 Level 属性描述元素在分层或损坏的层次结构中的位置。 例如，项目符号/编号列表、标题或其他结构化数据项可以具有各种父/子关系。 级别 描述项在结构中的位置。 建议将 CustomNavigation 控件模式 与 Level 结合使用。 变体类型： VT_I4 默认值：0 |
|
标识 LiveSetting 属性，该属性由表示实时区域的自动化元素支持。 LiveSetting 属性指示客户端应使用的“礼貌”级别，以通知用户实时区域发生更改。 此属性可以是 LiveSetting 枚举中的值之一。 从 Windows 8 开始受支持。 变体类型： VT_I4 默认值：0 |
|
标识 LocalizedControlType 属性，该属性是描述自动化元素所表示控件类型的文本字符串。 字符串应仅包含小写字符：
如果元素提供程序未指定 LocalizedControlType ，则框架根据元素的控件类型提供默认本地化字符串 (例如 Button 控件类型的 “button”) 。 具有 自定义 控件类型的自动化元素必须支持一个本地化的控件类型字符串，该字符串表示元素的角色 (例如，自定义控件的“颜色选取器”允许用户) 选择和指定颜色。 提供自定义值时，字符串必须与应用程序 UI 语言或操作系统默认 UI 语言匹配。 变体类型： VT_BSTR 默认值：空字符串 |
|
标识 LocalizedLandmarkType，它是描述自动化元素所表示的地标类型的文本字符串。 这应与 UIA_CustomLandmarkTypeId 但 LocalizedLandmarkType 应始终优先于 LandmarkType ，并用于在 LandmarkType 之前描述地标。 字符串必须与应用程序 UI 语言或操作系统默认 UI 语言匹配。 变体类型： VT_BSTR 默认值：空字符串 |
|
标识 Name 属性，该属性是保存自动化元素名称的字符串。 Name 属性应与屏幕上的标签文本相同。 例如，标签为“浏览”的按钮元素 的名称 应为“浏览”。 Name 属性不得包含访问键的助记字符， (即“&”) ，该字符在 UI 文本演示文稿中带有下划线。 此外， Name 属性不应是屏幕标签的扩展或修改版本，因为名称和标签之间的不一致可能会导致客户端应用程序和用户混淆。 当相应的标签文本在屏幕上不可见，或者当它被图形替换时，应选择替代文本。 替代文本应简洁、直观，并本地化为应用程序 UI 语言或操作系统默认 UI 语言。 替代文本不应是视觉详细信息的详细说明，而应是 UI 函数或功能的简明说明，就像用简单文本标记一样。 例如，Windows“开始”菜单按钮名为“开始” (按钮) 而不是“蓝色圆形图形上的 Windows 徽标” (按钮) 。 有关详细信息，请参阅 为图像创建文本等效项。 例如，当 UI 标签使用文本图形 (时，对从左到右) 添加项的按钮使用“>>”时， Name 属性应由适当的文本替代 (例如“添加”) 。 但是，由于本地化和辅助功能方面的考虑，不建议使用文本图形作为 UI 标签的做法。 Name 属性不得包含控件角色或类型信息，例如“按钮”或“列表”;否则，当这两个属性追加到许多现有辅助技术 (执行此操作) 时，它将与 LocalizedControlType 属性中的文本冲突。 Name 属性不能用作同级之间的唯一标识符。 但是，只要它与 UI 呈现一致，对等方就可以支持相同的 Name 值。 对于测试自动化，客户端应考虑使用 AutomationId 或 RuntimeId 属性。 只要也支持 Text 模式，文本控件不必始终使 Name 属性与控件中显示的 文本 相同。 变体类型： VT_BSTR 默认值：空字符串 |
|
标识 NativeWindowHandle 属性，该属性是一个整数，表示自动化元素窗口的 HWND) (句柄（如果存在）;否则，此属性为 0。 变体类型： VT_I4 默认值：0 |
|
标识 OptimizeForVisualContent 属性，该属性是一个布尔值，指示提供程序是否仅公开可见的元素。 当处理非常大的内容时，提供程序可以使用此属性来优化性能。 例如，当用户翻阅一大段内容时，提供程序可以销毁不再可见的内容元素。 销毁内容元素时，提供程序应返回 UIA_E_ELEMENTNOTAVAILABLE 错误代码。 从 Windows 8 开始受支持。 变体类型： VT_BOOL 默认值： FALSE |
|
标识 Orientation 属性，该属性指示由自动化元素表示的控件的方向。 属性表示为 OrientationType 枚举类型的值。 方向属性受控件（如滚动条和滑块）的支持，这些控件可以采用垂直或水平方向。 否则，它始终可以 OrientationType_None，这意味着控件没有方向。 变体类型： VT_I4 默认值：0 (OrientationType_None) |
|
标识 OutlineColor 属性，该属性指定用于自动化元素轮廓的颜色。 此属性指定为 COLORREF，这是用于指定 RGB 或 RGBA 颜色的 32 位值。 变体类型： VT_I4 | VT_ARRAY 默认值：0 |
|
标识 OutlineThickness 属性，该属性指定自动化元素的轮廓的宽度。 变体类型： VT_R8 | VT_ARRAY 默认值： VT_EMPTY |
|
标识 PositionInSet 属性，该属性是与自动化元素关联的从 1 开始的整数。 PositionInSet 描述一组被视为同级元素的元素中的元素的序号位置。 PositionInSet 与 SizeOfSet 属性协同工作，以描述集中的序号位置。 变体类型： VT_I4 默认值：0 |
|
标识 ProcessId 属性，该属性是一个整数，表示自动化元素的进程标识符 (ID) 。 ) 的进程标识符 (ID 由操作系统分配。 可以在任务管理器的“进程”选项卡的“PID”列中看到它。 变体类型： VT_I4 默认值：0 |
|
标识 ProviderDescription 属性，该属性是一个格式化字符串，其中包含自动化元素的 UI 自动化提供程序的源信息，包括代理信息。 变体类型： VT_BSTR 默认值：空字符串 |
|
标识 Rotation 属性，该属性指定以未指定的单位表示的旋转角度。 变体类型： VT_R8 默认值：0 |
|
标识 RuntimeId 属性，该属性是表示自动化元素标识符的整数数组。 标识符在桌面上是唯一的，但保证仅在生成该标识符的桌面 UI 中是唯一的。 标识符可以随时间推移重复使用。 RuntimeId 的格式可以更改。 返回的标识符应被视为不透明值，仅用于比较;例如，确定自动化元素是否在缓存中。 变体类型： VT_I4 | VT_ARRAY 默认值： VT_EMPTY |
|
标识 Size 属性，该属性指定自动化元素的宽度和高度。 变体类型： VT_R8 | VT_ARRAY 默认值： VT_EMPTY |
|
标识 SizeOfSet 属性，该属性是与自动化元素关联的从 1 开始的整数。 SizeOfSet 描述组或集中被视为同级元素的自动化元素计数。 SizeOfSet 与 PositionInSet 属性协同工作，以描述集中的项计数。 变体类型： VT_I4 默认值：0 |
|
标识 VisualEffects 属性，该属性是一个位字段，用于指定对自动化元素（如阴影、反射、发光、软边缘或棱台）的效果。 VisualEffects：
默认值：0 |
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 |
Windows XP [桌面应用 | UWP 应用] |
| 最低受支持的服务器 |
Windows Server 2003 [桌面应用 | UWP 应用] |
| Header |
|
请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈