Accessible QML Type

启用 QML 项目的可访问性。更多

Import Statement: import QtQuick

所有成员（包括继承成员）的列表
Accessible 是辅助功能类的一部分。

属性

checkStateMixed : bool
checkable : bool
checked : bool
defaultButton : bool
description : string
editable : bool
focusable : bool
focused : bool
id : string
ignored : bool
multiLine : bool
name : string
passwordEdit : bool
pressed : bool
readOnly : bool
role : enumeration
searchEdit : bool
selectable : bool
selectableText : bool
selected : bool

信号

方法

void announce(string message, AnnouncementPoliteness politeness) (since 6.8)

详细说明

该类是 Qt Quick 应用程序辅助功能的一部分。

用户与之交互或向用户提供信息的项目需要向辅助功能框架公开其信息。这样，辅助工具就可以利用这些信息，让用户以各种方式与应用程序进行交互。例如，这使得Qt Quick 应用程序可以与读屏器一起使用。

最重要的属性是name 、description 和role 。

一个简单按钮的实现示例：

Rectangle {
    id: myButton
    Text {
        id: label
        text: "next"
    }
    Accessible.role: Accessible.Button
    Accessible.name: label.text
    Accessible.description: "shows the next page"
    Accessible.onPressAction: {
        // do a button click
    }
}

role 设置为Button ，用于指示控件类型。name 是最重要的信息，与按钮上的文本绑定。名称是对控件简短而简明的描述，应反映视觉标签。在本例中，仅凭名称并不清楚按钮的作用，因此description 包含了解释。还有一个信号处理器Accessible.pressAction ，辅助工具可以调用它来触发按钮。该信号处理程序需要具有与点击或单击按钮相同的效果。

另请参阅 辅助功能。

属性文档

checkStateMixed : bool

此属性表示此项目是否处于部分选中状态。

默认情况下，该属性为false 。

另请参阅 checked 和checkable 。

checkable : bool

此属性表示此项目是否可选中（如复选框或某些按钮）。

默认情况下，此属性为false 。

另请参阅 checked 。

checked : bool

此属性表示此项目当前是否被选中。

默认情况下，此属性为false 。

另请参见 checkable 。

defaultButton : bool

此属性显示此项目是否为对话框的默认按钮。

默认情况下，此属性为false 。

description : string

该属性设置可访问的描述。与名称类似，它也是对项目的描述。描述可以更详细一些，并说明项目的作用，例如描述按钮的功能。

editable : bool

该属性显示该项目是否有可编辑文本。

默认情况下，该属性为false 。

focusable : bool

该属性显示该项目是否可聚焦。

默认情况下，此属性为false ，但角色为CheckBox,RadioButton,Button,MenuItem,PageTab,EditableText,SpinBox,ComboBox,Terminal 或ScrollBar 的项目除外。

另请参见 focused 。

focused : bool

此属性表示此项目当前是否有活动焦点。

默认情况下，该属性为false ，但对于QQuickItem::hasActiveFocus() 返回true 的项目，它将返回true 。

另请参阅 focusable 。

id : string

该属性设置了对象的标识符。它可用于为用户界面测试提供稳定的标识符。默认情况下，标识符设置为 QML 对象的 ID。如果 ID 未设置，则默认使用QAccessible::Identifier 。

ignored : bool

该属性表示该项目是否应被辅助功能框架忽略。

有时，一个项目是一组项目的一部分，应被视为一个项目。例如，两个标签在视觉上可能相邻，但却是不同的项目。出于无障碍访问的目的，它们应被视为一个整体，因此它们由第三个具有正确几何形状的不可见项来表示。

例如，速度显示会添加 "m/s "作为较小的标签：

Row {
    Label {
        id: speedLabel
        text: "Speed: 5"
        Accessible.ignored: true
    }
    Label {
        text: qsTr("m/s")
        Accessible.ignored: true
    }
    Accessible.role: Accessible.StaticText
    Accessible.name: speedLabel.text + " meters per second"
}

默认情况下，此属性为false 。

multiLine : bool

该属性表示该项目是否有多行文字。

默认情况下，此属性为false 。

name : string

该属性设置了一个可访问的名称。例如，对于按钮而言，该名称应与其文本绑定。一般来说，该属性应设置为一个简单、简洁但可读的名称。请勿包含您想表示的控件类型，只需包含名称即可。

passwordEdit : bool

此属性表示此项目是否为密码文本编辑器。

默认情况下，该属性为false 。

pressed : bool

该属性表示该项是否被按下（例如鼠标点击时的按钮）。

默认情况下，此属性为false 。

readOnly : bool

该属性表示文本字段只读。

当角色为QAccessible::EditableText 并设置为只读时，该属性才会相关。默认情况下，此属性为false 。

role : enumeration

该标志设置 widget 的语义类型。例如，按钮的类型为 "按钮"。其值必须是QAccessible::Role 中的一个。

某些角色具有特殊语义。例如，为了实现复选框，就需要 "checked "属性。

角色	属性和信号	说明
所有交互式元素	focusable 和focused	用户可以与之交互的所有元素都应将 focusable 设置为`true` ，并将`focus` 设置为`true` 。这一点即使对于在纯触摸设备上运行的应用程序也很重要，因为屏幕阅读器通常会实现一个虚拟焦点，可以从一个项目移动到另一个项目。
按钮，CheckBox 、RadioButton	Accessible.pressAction	按钮应有一个名为`onPressAction` 的信号处理器。该信号可由屏幕阅读器等辅助工具发出。执行时的行为应与鼠标点击或轻触按钮时的行为相同。
CheckBox,RadioButton	checkable checked 、Accessible.toggleAction	复选框的选中状态。更新了按下、选中和取消选中操作。
滑块,SpinBox, 拨号、ScrollBar	`value`,`minimumValue`,`maximumValue` 、`stepSize`	这些属性反映了元素的状态和可能的值。
Slider,SpinBox, Dial、ScrollBar	Accessible.increaseAction,Accessible.decreaseAction	用于增加和减少元素值的操作。

searchEdit : bool

此属性表示此项目是否为搜索查询的输入项。该属性只影响可编辑文本。

默认情况下，该属性为false 。

selectable : bool

此属性表示此项目是否可以选择。

默认情况下，此属性为false 。

另请参阅 selected 。

selectableText : bool

此属性表示此项目是否包含可选择文本。

默认情况下，此属性为false 。

selected : bool

此属性表示此项目是否被选中。

默认情况下，此属性为false 。

另请参见 selectable 。

信号文档

decreaseAction()

当从屏幕阅读器等辅助工具接收到减少操作时，将发出该信号。

注：相应的处理程序是onDecreaseAction 。

increaseAction()

从屏幕阅读器等辅助工具接收到增加操作时，会发出该信号。

注：相应的处理程序是onIncreaseAction 。

nextPageAction()

从屏幕阅读器等辅助工具接收到下一页操作时，会发出该信号。

注：相应的处理程序是onNextPageAction 。

pressAction()

从屏幕阅读器等辅助工具接收到按压操作时，会发出该信号。

注：相应的处理程序是onPressAction 。

previousPageAction()

从屏幕阅读器等辅助工具接收到上一页操作时，会发出该信号。

注：相应的处理程序是onPreviousPageAction 。

scrollDownAction()

从屏幕阅读器等辅助工具接收到向下滚动操作时，会发出该信号。

注：相应的处理程序是onScrollDownAction 。

scrollLeftAction()

从屏幕阅读器等辅助工具接收到向左滚动操作时，会发出该信号。

注：相应的处理程序是onScrollLeftAction 。

scrollRightAction()

从屏幕阅读器等辅助工具接收到向右滚动操作时，会发出该信号。

注：相应的处理程序是onScrollRightAction 。

scrollUpAction()

从屏幕阅读器等辅助工具接收到向上滚动操作时，会发出该信号。

注：相应的处理程序是onScrollUpAction 。

toggleAction()

从屏幕阅读器等辅助工具接收到切换操作时，会发出该信号。

注：相应的处理程序是onToggleAction 。

方法文档

[since 6.8] void announce(string message, AnnouncementPoliteness politeness)

用message 发布带有礼貌politeness 的公告事件。

该方法在 Qt 6.8 中引入。

另请参阅 QAccessibleAnnouncementEvent 。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.