En esta página

Guía de implementación

Descripción general

Este documento describe cómo implementar y utilizar el complemento « Qt Virtual Keyboard » con aplicaciones Qt.

Implementación

Los distintos complementos y archivos de Qt Virtual Keyboard se instalan en las siguientes ubicaciones:

ElementoRuta de instalación en el escritorioRuta de instalación de Boot2Qt
qtvirtualkeyboardplugin: complemento de contexto de entrada de la plataforma<QT_INSTALL_PLUGINS>/platforminputcontexts/system/plugins/platforminputcontexts
qtvkbplugin: complemento QML<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/system/qml/QtQuick/VirtualKeyboard
Complemento QML «qtvkbcomponentsplugin»<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Components/system/qml/QtQuick/VirtualKeyboard/Components
qtvkblayoutsplugin: complemento QML<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Layouts/system/qml/QtQuick/VirtualKeyboard/Layouts
qtvkbpluginsplugin: complemento QML<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Plugins/system/qml/QtQuick/VirtualKeyboard/Plugins
Complementos QML de la extensión<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Plugins/*/system/qml/QtQuick/VirtualKeyboard/Plugins/*
qtvkbsettingsplugin: complemento QML<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Settings/system/qml/QtQuick/VirtualKeyboard/Settings
qtvkbstylesplugin: complemento QML<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Styles/system/qml/QtQuick/VirtualKeyboard/Styles
Datos del teclado virtual<QT_INSTALL_DATA>/qtvirtualkeyboard/system/qtvirtualkeyboard

Dependencias

Más información en «Implementación de las bibliotecas de Qt».

Método de integración

Qt Virtual Keyboard Actualmente admite dos métodos de integración alternativos para utilizar el complemento:

  • Desktop: no requiere cambios en las aplicaciones existentes. El teclado virtual está disponible para todas las aplicaciones Qt del sistema.

    En este método de integración, el teclado se muestra en una ventana dedicada de nivel superior.

  • Application: el teclado virtual se integra directamente en la propia aplicación Qt mediante la instanciación de un elemento ` InputPanel ` en QML.

    Este método es obligatorio en entornos en los que no se admiten varias ventanas de nivel superior (como los dispositivos integrados), pero también puede utilizarse en aplicaciones de escritorio.

    Los Qt Wayland Compositors también pueden utilizar este método para proporcionar un teclado virtual del lado del servidor. Consulta la sección siguiente para obtener más detalles.

El método de integración se selecciona automáticamente mediante los archivos del proyecto. Sin embargo, en entornos de escritorio, es posible anular el método de integración de escritorio y utilizar en su lugar el método de integración de la aplicación, mediante la variable de entorno QT_VIRTUALKEYBOARD_DESKTOP_DISABLE o añadiendo -no-vkb-desktop a la línea de comandos de configure.

Uso de ` Qt Virtual Keyboard ` con Qt Wayland

En esta sección se explica cómo utilizar Qt Virtual Keyboard para interactuar con el ejemplo «Qt Widgets Line Edits» utilizando el ejemplo «Fancy Compositor» como compositor.

Utilizaremos Ubuntu 18.04 para ejecutar el ejemplo, con X11 como sistema de ventanas. El compositor del ejemplo (fancy-compositor) se abrirá como una ventana dentro de una sesión de X11.

  1. Inicia el compositor:
    QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_CLIENT_BUFFER_INTEGRATION=xcomposite-egl \
    QT_IM_MODULE=qtvirtualkeyboard ./fancy-compositor -platform xcb
  2. Antes de ejecutar la aplicación cliente, asegúrate de que QT_IM_MODULE no esté definido:
    unset QT_IM_MODULE
  3. Inicia el ejemplo «Line Edits» como cliente:
    ./lineedits -platform wayland
  4. Haz clic en un campo de edición de línea y se abrirá el panel de entrada de Qt Virtual Keyboard.

Si surgen problemas, se pueden configurar las siguientes variables de entorno al ejecutar el compositor para obtener información de depuración que ayude a diagnosticar el problema:

WAYLAND_DEBUG=1
QT_LOGGING_RULES="qt.virtualkeyboard=true;qt.qpa.wayland*=true"

Carga del complemento

En ambos métodos de integración, la aplicación debe utilizar la variable de entorno QT_IM_MODULE para cargar el complemento. Por ejemplo:

$ QT_IM_MODULE=qtvirtualkeyboard myapp

o en la función main():

qputenv("QT_IM_MODULE", QByteArray("qtvirtualkeyboard"));

En el método de integración de escritorio, este paso es todo lo que se necesita para utilizar Qt Virtual Keyboard. En el método de integración de la aplicación, es necesario que la aplicación cree una instancia de InputPanel, tal y como se explica en el siguiente capítulo.

Creación de InputPanel

El siguiente ejemplo muestra cómo crear un InputPanel y cómo dividir el área de la pantalla con el contenedor de la aplicación.

import QtQuick
import QtQuick.VirtualKeyboard

Item {
    id: root
    Item {
        id: appContainer
        anchors.left: parent.left
        anchors.top: parent.top
        anchors.right: parent.right
        anchors.bottom: inputPanel.top
        ...
    }
    InputPanel {
        id: inputPanel
        y: Qt.inputMethod.visible ? parent.height - inputPanel.height : parent.height
        anchors.left: parent.left
        anchors.right: parent.right
    }
}

El panel de entrada debe ser un elemento hermano situado junto al contenedor de la aplicación. Es importante no colocar el panel de entrada dentro del contenedor de la aplicación, ya que, de hacerlo, se superpondría con el contenido de la aplicación. Además, la altura del panel de entrada se actualizará automáticamente en función del ancho disponible; la relación de aspecto del panel de entrada es constante.

Parámetros del complemento

Algunos parámetros pueden especificarse añadiéndolos al valor del QT_IM_MODULE (tras dos puntos), por ejemplo, QT_IM_MODULE=qtvirtualkeyboard:wordCandidateListVisible. Otros parámetros son pares clave-valor separados por "=".

ParámetroFinalidad
wordCandidateListVisibleMuestra la lista de palabras candidatas.
wordCandidateListAutoCommitWordActiva la función AutoCommit para la lista de palabras candidatas.
pantalla completaUtilizar el modo de pantalla completa
style=<nombre>Establece el estilo
locale=<nombre>Establecer la configuración regional

Variables de entorno

El módulo define varias variables de entorno, que se enumeran a continuación:

VariableFinalidad
QT_VIRTUALKEYBOARD_HUNSPELL_DATA_PATHAnula la ubicación de los archivos de datos de Hunspell.

La ubicación por defecto depende del valor de ` QLibraryInfo::path(QLibraryInfo::DataPath)`. Por ejemplo, para las bibliotecas Qt compiladas a partir del código fuente, podría ser ` qtbase/qtvirtualkeyboard/hunspell`.

Consulte Integración de Hunspell para obtener más información.

QT_VIRTUALKEYBOARD_PINYIN_DICTIONARYAnula la ubicación del diccionario Pinyin.

Por defecto, el diccionario se incluye en los recursos del complemento.

Para desactivar la inclusión de recursos, añade -vkb-no-bundle-pinyin a la línea de comandos de configuración de Qt. En este caso, la ubicación predeterminada depende del valor de ` QLibraryInfo::path(QLibraryInfo::DataPath)`. Por ejemplo, para las bibliotecas de Qt compiladas a partir del código fuente, podría ser ` qtbase/qtvirtualkeyboard/pinyin/dict_pinyin.dat`.

QT_VIRTUALKEYBOARD_CANGJIE_DICTIONARYAnula la ubicación del diccionario Cangjie.

Por defecto, el diccionario viene incluido en los recursos del complemento.

Para desactivar la inclusión de recursos, añade -vkb-no-bundle-tcime a la línea de comandos de configuración de Qt. En este caso, la ubicación por defecto depende del valor de ` QLibraryInfo::path(QLibraryInfo::DataPath)`. Por ejemplo, para las bibliotecas de Qt compiladas a partir del código fuente, podría ser ` qtbase/qtvirtualkeyboard/tcime/dict_cangjie.dat`.

QT_VIRTUALKEYBOARD_ZHUYIN_DICTIONARYAnula la ubicación del diccionario Zhuyin.

Por defecto, el diccionario se incluye en los recursos del complemento.

Para desactivar la inclusión de recursos, añade -vkb-no-bundle-tcime a la línea de comandos de configuración de Qt. En este caso, la ubicación predeterminada depende del valor de ` QLibraryInfo::path(QLibraryInfo::DataPath)`. Por ejemplo, para las bibliotecas de Qt compiladas a partir del código fuente, podría ser ` qtbase/qtvirtualkeyboard/tcime/dict_zhuyin.dat`.

QT_VIRTUALKEYBOARD_PHRASE_DICTIONARYAnula la ubicación del diccionario de frases.

Por defecto, el diccionario se incluye en los recursos del complemento.

Para desactivar la inclusión de recursos, añade -vkb-no-bundle-tcime a la línea de comandos de configuración de Qt. En este caso, la ubicación por defecto depende del valor de ` QLibraryInfo::path(QLibraryInfo::DataPath)`. Por ejemplo, para las bibliotecas de Qt compiladas a partir del código fuente, podría ser ` qtbase/qtvirtualkeyboard/tcime/dict_phrases.dat`.

QT_VIRTUALKEYBOARD_CERENCE_HWR_DB_PATHEspecifica la ubicación de la base de datos de escritura manuscrita de Cerence Handwriting.

Las ubicaciones de búsqueda predeterminadas para la base de datos de escritura manuscrita de Cerence Handwriting son:

  • QT_VIRTUALKEYBOARD_CERENCE_HWR_DB_PATH
  • QLibraryInfo::location(QLibraryInfo::DataPath) + "/qtvirtualkeyboard/cerence/handwriting"
  • ":/qt-project.org/imports/QtQuick/VirtualKeyboard/Cerence/Handwriting"

La variable de entorno puede contener varias rutas. Las rutas se separan con punto y coma en Windows y con dos puntos en otros sistemas operativos.

QT_VIRTUALKEYBOARD_XT9_LDB_PATHEspecifica la ubicación de las bases de datos XT9.

Las rutas de búsqueda predeterminadas para los archivos LDB son:

  • QT_VIRTUALKEYBOARD_XT9_LDB_PATH
  • QLibraryInfo::location(QLibraryInfo::DataPath) + "/qtvirtualkeyboard/cerence/xt9"
  • ":/qt-project.org/imports/QtQuick/VirtualKeyboard/Cerence/Xt9"

Se pueden especificar rutas de búsqueda adicionales configurando esta variable de entorno. Las rutas múltiples se separan con punto y coma en Windows y con dos puntos en otros sistemas operativos.

Los archivos LDB son compartidos entre los complementos XT9 y Cerence Handwriting, por lo que esta variable de entorno afecta a ambos complementos.

QT_VIRTUALKEYBOARD_STYLEEspecifica la ubicación del estilo que se va a utilizar con el teclado virtual.

Esto también se puede especificar en QML estableciendo ` VirtualKeyboardSettings::styleName`, o en el momento de la compilación utilizando las opciones de configuración.

QT_VIRTUALKEYBOARD_LAYOUT_PATHEspecifica la ubicación de las distribuciones que se utilizarán con el teclado virtual.
QT_VIRTUALKEYBOARD_DESKTOP_DISABLEDesactiva el método de integración con el escritorio.
QT_VIRTUALKEYBOARD_FORCE_EVENTS_WITHOUT_FOCUSHabilita Qt Virtual Keyboard para enviar eventos de teclas y utilizar la tecla Mayús sin que haya ningún campo de entrada de texto activo.

Esta variable debe configurarse explícitamente en el entorno de ejecución de una aplicación que desee beneficiarse de ello. No basta con utilizar ` qputenv()` en la propia aplicación.

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