En esta página

Accessible QML Type (Uncreatable)

Habilita la accesibilidad de los elementos QML. Más...

Import Statement: import QtQuick

Nota: Se trata de un tipo no creable. No se puede instanciar en QML.

Propiedades

Señales

Métodos

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

Descripción detallada

Esta clase forma parte de la Accesibilidad para aplicaciones de Qt Quick .

Los elementos con los que el usuario interactúa o que le proporcionan información deben exponer dicha información al marco de accesibilidad. De este modo, las herramientas de asistencia pueden utilizar esa información para permitir a los usuarios interactuar con la aplicación de diversas formas. Esto permite, por ejemplo, utilizar aplicaciones Qt Quick con lectores de pantalla.

Las propiedades más importantes son name, description y role.

Ejemplo de implementación de un botón sencillo:

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
    }
}

La propiedad « role » se establece en « Button » para indicar el tipo de control. « name » es la información más importante y está vinculada al texto del botón. El «name» es una descripción breve y concisa del control y debe reflejar la etiqueta visual. En este caso, no queda claro qué hace el botón solo con el nombre, por lo que « description » contiene una explicación. También hay un controlador de señales Accessible.pressAction que pueden invocar las herramientas de asistencia para activar el botón. Este controlador de señales debe tener el mismo efecto que tendría pulsar o hacer clic en el botón.

Véase también Accesibilidad.

Documentación de propiedades

checkStateMixed : bool

Esta propiedad indica si este elemento se encuentra en estado «parcialmente marcado».

Por defecto, esta propiedad es « false ».

Véase también « checked » y « checkable ».

checkable : bool

Esta propiedad indica si este elemento se puede marcar (como una casilla de selección o algunos botones).

Por defecto, esta propiedad es « false ».

Véase también « checked ».

checked : bool

Esta propiedad indica si este elemento está marcado actualmente.

Por defecto, esta propiedad tiene el valor « false ».

Véase también « checkable ».

defaultButton : bool

Esta propiedad indica si este elemento es el botón predeterminado de un cuadro de diálogo.

De forma predeterminada, esta propiedad tiene el valor « false ».

description : string

Esta propiedad establece una descripción accesible. Al igual que el nombre, describe el elemento. La descripción puede ser un poco más detallada y explicar para qué sirve el elemento; por ejemplo, la funcionalidad del botón al que se refiere.

editable : bool

Esta propiedad indica si este elemento contiene texto editable.

Por defecto, esta propiedad tiene el valor « false ».

expandable : bool [since 6.12]

Esta propiedad indica si este elemento es expandible.

Por defecto, esta propiedad tiene el valor « false ».

Esta propiedad se introdujo en Qt 6.12.

Véase también « expanded ».

expanded : bool [since 6.12]

Esta propiedad indica si este elemento está desplegado actualmente.

Por defecto, esta propiedad tiene el valor « false ».

Esta propiedad se introdujo en Qt 6.12.

Véase también « expandable ».

focusable : bool

Esta propiedad indica si se puede seleccionar este elemento.

Por defecto, esta propiedad es « false », salvo en el caso de los elementos cuyo rol sea uno de los siguientes: « CheckBox », « RadioButton », « Switch », « Button », « MenuItem », « PageTab », « EditableText », « SpinBox », « ComboBox », « Terminal » o « ScrollBar ».

Véase también focused.

focused : bool

Esta propiedad indica si este elemento tiene actualmente el foco activo.

Por defecto, esta propiedad es false, pero devolverá true para aquellos elementos cuyo método QQuickItem::hasActiveFocus() devuelva true.

Véase también focusable.

id : string

Esta propiedad establece un identificador para el objeto. Se puede utilizar para proporcionar identificadores estables a las pruebas de la interfaz de usuario. Por defecto, el identificador se establece en el ID del objeto QML. Si no se ha definido el ID, se utiliza el valor por defecto « QAccessible::Identifier ».

ignored : bool

Esta propiedad determina si el marco de accesibilidad debe ignorar este elemento.

A veces, un elemento forma parte de un grupo de elementos que deben tratarse como uno solo. Por ejemplo, dos etiquetas pueden estar situadas visualmente una al lado de la otra, pero ser elementos independientes. A efectos de accesibilidad, deben tratarse como uno solo y, por lo tanto, se representan mediante un tercer elemento invisible con la geometría adecuada.

Por ejemplo, un indicador de velocidad añade «m/s» como una etiqueta más pequeña:

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"
}

Por defecto, esta propiedad está est false.

labelFor : Item [since 6.10]

Esta propiedad contiene el elemento al que corresponde esta etiqueta.

Al establecer esta propiedad, se configura automáticamente la relación « labelledBy » del otro objeto.

Por defecto, esta propiedad tiene el valor « undefined ».

Esta propiedad se introdujo en Qt 6.10.

labelledBy : Item [since 6.10]

Esta propiedad contiene el elemento que se utiliza como etiqueta para este elemento.

Al establecer esta propiedad, se configura automáticamente la relación « labelFor » del otro objeto.

Por defecto, esta propiedad es « undefined ».

Esta propiedad se introdujo en Qt 6.10.

multiLine : bool

Esta propiedad indica si este elemento tiene varias líneas de texto.

Por defecto, esta propiedad tiene el valor « false ».

name : string

Esta propiedad establece un nombre accesible. En el caso de un botón, por ejemplo, debería estar vinculada a su texto. En general, esta propiedad debe configurarse con un nombre sencillo y conciso, pero legible para las personas. No incluyas el tipo de control que deseas representar, sino solo el nombre.

passwordEdit : bool

Esta propiedad indica si este elemento es un campo de texto para contraseña.

Por defecto, esta propiedad tiene el valor « false ».

pressed : bool

Esta propiedad indica si se está pulsando este elemento (por ejemplo, un botón al hacer clic con el ratón).

Por defecto, esta propiedad tiene el valor « false ».

readOnly : bool

Esta propiedad indica que un campo de texto es de solo lectura.

Es relevante cuando el rol es « QAccessible::EditableText » y está configurado como de solo lectura. Por defecto, esta propiedad es « false ».

role : enumeration

Este indicador establece el tipo semántico del widget. Un botón, por ejemplo, tendría como tipo «Button». El valor debe ser uno de los siguientes: QAccessible::Role.

Algunas funciones tienen una semántica especial. Para implementar casillas de selección, por ejemplo, se espera una propiedad «checked».

RolPropiedades y señalesExplicación
Todos los elementos interactivosfocusable y focusedTodos los elementos con los que el usuario pueda interactuar deben tener la propiedad «focusable» establecida en « true » y la propiedad « focus » establecida en « true » cuando tengan el foco. Esto es importante incluso para aplicaciones que se ejecutan en dispositivos exclusivamente táctiles, ya que los lectores de pantalla suelen implementar un foco virtual que se puede desplazar de un elemento a otro.
Botón, « CheckBox », « RadioButton », InterruptorAccessible.pressActionUn botón debe tener un controlador de señal con el nombre onPressAction. Esta señal puede ser emitida por una herramienta de asistencia, como un lector de pantalla. La implementación debe comportarse igual que un clic con el ratón o un toque sobre el botón.
CheckBox, « RadioButton », «Switch»checkable, checked, Accessible.toggleActionEl estado de selección de la casilla de verificación. Se actualiza al pulsar, marcar y desmarcar.
Control deslizante, SpinBox, Dial, ScrollBarvalue, minimumValue, maximumValue, stepSizeEstas propiedades reflejan el estado y los valores posibles de los elementos.
Control deslizante, SpinBox, Dial, ScrollBarAccessible.increaseAction, Accessible.decreaseActionAcciones para aumentar y disminuir el valor del elemento.

searchEdit : bool

Esta propiedad indica si este elemento se utiliza como entrada para una consulta de búsqueda. Esta propiedad solo afecta al texto editable.

Por defecto, esta propiedad tiene el valor « false ».

selectable : bool

Esta propiedad indica si este elemento se puede seleccionar.

Por defecto, esta propiedad es « false ».

Véase también « selected ».

selectableText : bool

Esta propiedad indica si este elemento contiene texto seleccionable.

Por defecto, esta propiedad tiene el valor « false ».

selected : bool

Esta propiedad indica si este elemento está seleccionado.

Por defecto, esta propiedad es « false ».

Véase también « selectable ».

Documentación de Signal

decreaseAction()

Esta señal se emite cuando se recibe una acción de reducción procedente de una herramienta de accesibilidad, como un lector de pantalla.

Nota: El controlador correspondiente es onDecreaseAction.

increaseAction()

Esta señal se emite cuando se recibe una acción de «aumentar» procedente de una herramienta de accesibilidad, como un lector de pantalla.

Nota: El controlador correspondiente es onIncreaseAction.

nextPageAction()

Esta señal se emite cuando se recibe una acción de «página siguiente» procedente de una herramienta de accesibilidad, como un lector de pantalla.

Nota: El controlador correspondiente es onNextPageAction.

pressAction()

Esta señal se emite cuando se recibe una acción de pulsación procedente de una herramienta de apoyo, como un lector de pantalla.

Nota: El controlador correspondiente es onPressAction.

previousPageAction()

Esta señal se emite cuando se recibe una acción de página anterior procedente de una herramienta de accesibilidad, como un lector de pantalla.

Nota: El controlador correspondiente es onPreviousPageAction.

scrollDownAction()

Esta señal se emite cuando se recibe una acción de desplazamiento hacia abajo procedente de una herramienta de accesibilidad, como un lector de pantalla.

Nota: El controlador correspondiente es onScrollDownAction.

scrollLeftAction()

Esta señal se emite cuando se recibe una acción de desplazamiento hacia la izquierda procedente de una herramienta de accesibilidad, como un lector de pantalla.

Nota: El controlador correspondiente es onScrollLeftAction.

scrollRightAction()

Esta señal se emite cuando se recibe una acción de desplazamiento hacia la derecha procedente de una herramienta de accesibilidad, como un lector de pantalla.

Nota: El controlador correspondiente es onScrollRightAction.

scrollUpAction()

Esta señal se emite cuando se recibe una acción de desplazamiento hacia arriba procedente de una herramienta de accesibilidad, como un lector de pantalla.

Nota: El controlador correspondiente es onScrollUpAction.

showOnScreenAction()

Esta señal se emite cuando una herramienta de accesibilidad, como un lector de pantalla, detecta un elemento parcialmente visible y solicita que se muestre en su totalidad.

Nota: El controlador correspondiente es onShowOnScreenAction.

toggleAction()

Esta señal se emite cuando se recibe una acción de alternancia procedente de una herramienta de apoyo, como un lector de pantalla.

Nota: El controlador correspondiente es onToggleAction.

Documentación del método

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

Emite un evento de notificación con un ` message ` con el nivel de cortesía ` politeness`.

Este método se introdujo en Qt 6.8.

Véase también QAccessibleAnnouncementEvent.

© 2026 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.