En esta página

Cómo crear complementos de Qt

Qt ofrece dos API para crear complementos:

  • Una API de alto nivel para escribir extensiones para el propio Qt, como controladores de bases de datos personalizados, formatos de imagen, códecs de texto y estilos.
  • Una API de bajo nivel para ampliar las aplicaciones de Qt.

Por ejemplo, si quieres escribir una subclase personalizada de ` QStyle ` y que las aplicaciones de Qt la carguen dinámicamente, deberías utilizar la API de alto nivel.

Dado que la API de alto nivel se basa en la API de bajo nivel, hay algunos problemas que son comunes a ambas.

Si quieres proporcionar complementos para su uso con Qt Widgets Designer, consulta «Creación de complementos de widgets personalizados».

La API de alto nivel: cómo escribir extensiones de Qt

Para escribir un complemento que amplíe el propio Qt, basta con crear una subclase de la clase base de complementos adecuada, implementar unas cuantas funciones y añadir una macro.

Existen varias clases base de complementos. Los complementos derivados se almacenan, por defecto, en subdirectorios del directorio estándar de complementos. Qt no encontrará los complementos si no están almacenados en el directorio adecuado.

La siguiente tabla resume las clases base de los complementos. Algunas de las clases son privadas y, por lo tanto, no están documentadas. Puedes utilizarlas, pero no hay garantía de compatibilidad con versiones posteriores de Qt.

Clase baseNombre del directorioMódulo QtDistinción entre mayúsculas y minúsculas
QAccessibleBridgePluginaccessiblebridgeQt GUIDistingue entre mayúsculas y minúsculas
QImageIOPluginimageformatsQt GUIDistingue entre mayúsculas y minúsculas
QPictureFormatPlugin (obsoleto)pictureformatsQt GUIDistingue entre mayúsculas y minúsculas
QBearerEnginePluginbearerQt NetworkDistingue entre mayúsculas y minúsculas
QPlatformInputContextPluginplatforminputcontextsAbstracción de la plataforma QtSin distinción entre mayúsculas y minúsculas
QPlatformIntegrationPluginplatformsAbstracción de la plataforma QtIndiferente a mayúsculas y minúsculas
QPlatformThemePluginplatformthemesAbstracción de la plataforma QtIndiferente a mayúsculas y minúsculas
QPlatformPrinterSupportPluginprintsupportQt Print SupportSin distinción entre mayúsculas y minúsculas
QSGContextPluginscenegraphQt QuickDistingue entre mayúsculas y minúsculas
QSqlDriverPluginsqldriversQt SQLDistingue entre mayúsculas y minúsculas
QIconEnginePluginiconenginesQt SVGSin distinción entre mayúsculas y minúsculas
QAccessiblePluginaccessibleQt WidgetsDistingue entre mayúsculas y minúsculas
QStylePluginstylesQt WidgetsSin distinción entre mayúsculas y minúsculas

Si tienes una nueva clase de visor de documentos llamada « JsonViewer » que quieres que esté disponible como complemento, la clase debe definirse de la siguiente manera (jsonviewer.h):

class JsonViewer : public ViewerInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.DocumentViewer.ViewerInterface/1.0" FILE "jsonviewer.json")
    Q_INTERFACES(ViewerInterface)
public:
    JsonViewer();
    ~JsonViewer() override;
private:
    void retranslate() override;
    bool openJsonFile();

    QTreeView *m_tree = nullptr;
    QListWidget *m_toplevel = nullptr;
    QJsonDocument m_root;
    QAction *m_expandAllAction = nullptr;
    QAction *m_collapseAllAction = nullptr;
};

Asegúrate de que la implementación de la clase se encuentre en un archivo .cpp:

JsonViewer::JsonViewer()
    : m_expandAllAction(new QAction(this)),
      m_collapseAllAction(new QAction(this))

{
    connect(this, &AbstractViewer::uiInitialized, this, &JsonViewer::setupJsonUi);

    m_expandAllAction->setIcon(QIcon::fromTheme(QIcon::ThemeIcon::ZoomIn));
    m_collapseAllAction->setIcon(QIcon::fromTheme(QIcon::ThemeIcon::ZoomOut));
}

void JsonViewer::init(QFile *file, QWidget *parent, QMainWindow *mainWindow)
{
    AbstractViewer::init(file, new QTreeView(parent), mainWindow);
    setTranslationBaseName("jsonviewer"_L1);
    m_tree = qobject_cast<QTreeView *>(widget());
}

Además, para la mayoría de los complementos se requiere un archivo JSON (jsonviewer.json) que contenga metadatos que describan el complemento. En el caso de los complementos de visor de documentos, este archivo contiene simplemente el nombre del complemento de visor.

{ "Keys": [ "jsonviewer" ] }

El tipo de información que debe proporcionarse en el archivo JSON depende del complemento. Consulte la documentación de la clase para obtener más detalles sobre la información que debe incluir el archivo.

En el caso de los controladores de bases de datos, los formatos de imagen, los códecs de texto y la mayoría de los demás tipos de complementos, no es necesaria la creación explícita de objetos. Qt los buscará y creará según sea necesario.

Las clases de complementos pueden requerir la implementación de funciones adicionales. Consulte la documentación de la clase para obtener más detalles sobre las funciones virtuales que deben reimplementarse para cada tipo de complemento.

La demostración del visor de documentos muestra cómo implementar un complemento que muestre el contenido estructurado de un archivo. Por lo tanto, cada complemento reimplementa funciones virtuales, que

  • identifican el complemento
  • devuelven los tipos MIME que admite
  • indican si hay contenido que mostrar y
  • cómo se presenta dicho contenido
    QString viewerName() const override { return QLatin1StringView(staticMetaObject.className()); };
    QStringList supportedMimeTypes() const override;
    bool hasContent() const override;
    bool supportsOverview() const override { return true; }

La API de bajo nivel: ampliación de aplicaciones Qt

Además del propio Qt, las aplicaciones Qt pueden ampliarse mediante complementos. Para ello, la aplicación debe detectar y cargar los complementos utilizando QPluginLoader. En este contexto, los complementos pueden proporcionar cualquier funcionalidad y no se limitan a controladores de bases de datos, formatos de imagen, códecs de texto, estilos y otros tipos de complementos que amplían la funcionalidad de Qt.

Para hacer que una aplicación sea extensible mediante complementos, hay que seguir los siguientes pasos:

  1. Definir un conjunto de interfaces (clases con solo funciones virtuales puras) que se utilicen para comunicarse con los complementos.
  2. Utilizar la macro Q_DECLARE_INTERFACE() para informar al sistema de metaobjetos de Qt sobre la interfaz.
  3. Utilizar ` QPluginLoader ` en la aplicación para cargar los complementos.
  4. Utilizar ` qobject_cast()` para comprobar si un complemento implementa una interfaz determinada.

La creación de un complemento implica los siguientes pasos:

  1. Declara una clase de complemento que herede de ` QObject ` y de las interfaces que el complemento quiera proporcionar.
  2. Utiliza la macro Q_INTERFACES() para informar al sistema de metaobjetos de Qt sobre las interfaces.
  3. Exportar el complemento utilizando la macro ` Q_PLUGIN_METADATA()`.

Por ejemplo, esta es la definición de una clase de interfaz:

class ViewerInterface : public AbstractViewer
{
public:
    virtual ~ViewerInterface() = default;
};

Esta es la declaración de la interfaz:

#define ViewerInterface_iid "org.qt-project.Qt.Examples.DocumentViewer.ViewerInterface/1.0"
Q_DECLARE_INTERFACE(ViewerInterface, ViewerInterface_iid)

Consulta también «Creación de widgets personalizados para Qt Widgets Designer » para obtener información sobre cuestiones específicas de Qt Widgets Designer. Consulta el «Ejemplo de plugin de backend de calendario» para ver un ejemplo del uso de un plugin para añadir compatibilidad con un sistema de calendario personalizado.

Localización de complementos

Las aplicaciones Qt detectan automáticamente qué complementos están disponibles, ya que estos se almacenan en los subdirectorios estándar de complementos. Por este motivo, las aplicaciones no necesitan ningún código para buscar y cargar complementos, ya que Qt se encarga de ello automáticamente.

Durante el desarrollo, el directorio de los complementos es QTDIR/plugins (donde QTDIR es el directorio en el que está instalado Qt), y cada tipo de complemento se encuentra en un subdirectorio específico para ese tipo, por ejemplo, styles. Si quieres que tus aplicaciones utilicen complementos y no deseas emplear la ruta estándar de los complementos, haz que tu proceso de instalación determine la ruta que deseas utilizar para los complementos y guarda dicha ruta, por ejemplo, mediante QSettings, para que la aplicación la lea cuando se ejecute. A continuación, la aplicación puede llamar a ` QCoreApplication::addLibraryPath()` con esta ruta y tus complementos estarán disponibles para la aplicación. Ten en cuenta que la parte final de la ruta (por ejemplo, ` styles`) no se puede modificar.

Si desea que el complemento se pueda cargar, una opción es crear un subdirectorio dentro de la aplicación y colocar el complemento en ese directorio. Si distribuyes alguno de los complementos que vienen con Qt (los que se encuentran en el directorio plugins ), debes copiar el subdirectorio de plugins donde se encuentra el complemento a la carpeta raíz de tu aplicación (es decir, no incluyas el directorio plugins ).

Para obtener más información sobre la implementación, consulta la documentación «Implementación de aplicaciones Qt » e «Implementación de complementos ».

Complementos estáticos

La forma habitual y más flexible de incluir un complemento en una aplicación es compilarlo en una biblioteca dinámica que se distribuya por separado y que se detecte y cargue en tiempo de ejecución.

Los complementos se pueden vincular de forma estática a tu aplicación. Si compilas la versión estática de Qt, esta es la única opción para incluir los complementos predefinidos de Qt. El uso de complementos estáticos hace que la implementación sea menos propensa a errores, pero tiene el inconveniente de que no se puede añadir ninguna funcionalidad de los complementos sin una recompilación y redistribución completas de la aplicación.

CMake y qmake añaden automáticamente los complementos que suelen necesitar los módulos de Qt utilizados, mientras que los complementos más especializados deben añadirse manualmente. La lista predeterminada de complementos añadidos automáticamente puede modificarse por tipo.

Los valores predeterminados están ajustados para ofrecer una experiencia óptima desde el primer momento, pero pueden sobrecargar innecesariamente la aplicación. Se recomienda revisar la línea de comandos del enlazador y eliminar los complementos innecesarios.

Para que los complementos estáticos se enlacen e instancien realmente, también se necesitan en el código de la aplicación las macros ` Q_IMPORT_PLUGIN()`, pero estas son generadas automáticamente por el sistema de compilación y añadidas al proyecto de tu aplicación.

Importación de complementos estáticos en CMake

Para vincular plugins de forma estática en un proyecto de CMake, es necesario llamar al comando ` qt_import_plugins() `.

Por ejemplo, el complemento « libinput » de Linux no se importa de forma predeterminada. El siguiente comando lo importa:

qt_import_plugins(myapp INCLUDE Qt::QLibInputPlugin)

Para vincular el complemento de integración de plataforma mínima en lugar del complemento de Qt Platform Adaptation predeterminado, utiliza:

qt_import_plugins(myapp
    INCLUDE_BY_TYPE platforms Qt::MinimalIntegrationPlugin
)

Otro caso de uso habitual es vincular solo un conjunto determinado de complementos « imageformats »:

qt_import_plugins(myapp
    INCLUDE_BY_TYPE imageformats Qt::QJpegPlugin Qt::QGifPlugin
)

Si quieres evitar que se vincule cualquier plugin de imageformats, utiliza:

qt_import_plugins(myapp
    EXCLUDE_BY_TYPE imageformats
)

Si quieres desactivar la inclusión de cualquier complemento predeterminado, utiliza la opción « NO_DEFAULT » de qt_import_plugins().

Importación de complementos estáticos en qmake

En un proyecto de qmake, debes añadir los complementos necesarios a tu compilación utilizando QTPLUGIN:

QTPLUGIN += qlibinputplugin

Por ejemplo, para vincular el complemento «minimal» en lugar del complemento predeterminado de Qt Platform Adaptation, utiliza:

QTPLUGIN.platforms = qminimal

Si no quieres que se vincule automáticamente ni el complemento predeterminado ni el mínimo de QPA, utiliza:

QTPLUGIN.platforms = -

Si no quieres que todos los complementos añadidos a QTPLUGIN se vinculen automáticamente, elimina « import_plugins » de la variable « CONFIG »:

CONFIG -= import_plugins

Creación de complementos estáticos

También es posible crear sus propios complementos estáticos siguiendo estos pasos:

  1. Pasa la opción « STATIC » al comando «qt_add_plugin() » en tu archivo « CMakeLists.txt ». Para un proyecto qmake, añade « CONFIG += static » al archivo « .pro » de tu complemento.
  2. Utiliza la macro Q_IMPORT_PLUGIN() en tu aplicación.
  3. Utiliza la macro Q_INIT_RESOURCE() en tu aplicación si el complemento incluye archivos qrc.
  4. Enlaza tu aplicación con la biblioteca del complemento utilizando ` target_link_libraries ` en tu archivo ` CMakeLists.txt ` o ` LIBS ` en tu archivo ` .pro `.

Consulta el ejemplo «Plug & Paint» y el complemento «Basic Tools» asociado para obtener más detalles sobre cómo hacerlo.

Nota: Si no utilizas CMake o qmake para compilar tu complemento, debes asegurarte de que la macro del preprocesador ` QT_STATICPLUGIN ` esté definida.

Carga de complementos

Los tipos de complementos (estáticos o compartidos) y los sistemas operativos requieren enfoques específicos para localizar y cargar los complementos. Resulta útil implementar una abstracción para la carga de complementos.

void ViewerFactory::loadViewerPlugins()
{
    if (!m_viewers.isEmpty())
        return;

QPluginLoader::staticInstances() devuelve un objeto ` QObjectList ` con un puntero a cada complemento vinculado estáticamente

    // Load static plugins
    const QObjectList &staticPlugins = QPluginLoader::staticInstances();
    for (auto *plugin : staticPlugins)
        addViewer(plugin);

Los complementos compartidos residen en sus directorios de implementación, lo que puede requerir un tratamiento específico según el sistema operativo.

   // Cargar complementos compartidos
    QDir pluginsDir = QDir(QApplication::applicationDirPath());
#if defined(Q_OS_DARWIN)
    if (pluginsDir.exists("../PlugIns"_L1)) { // compilación instalada
        pluginsDir.cd("../PlugIns"_L1);
    } else {
        pluginsDir.cd("../../../../plugins"_L1); // compilación sin instalar
    }
#elif defined(Q_OS_WIN)
    if (pluginsDir.exists("plugins"_L1)) { // compilación sin plugins instalados
        pluginsDir.cd("plugins"_L1);
    } else {
        pluginsDir.cd("../plugins"_L1); // compilación con plugins instalados
    }
#else
    pluginsDir.cd("../plugins"_L1); // compilación con y sin plugins instalados
#endif

   // qDebug("Cargando complementos desde %s...", qUtf8Printable(pluginsDir.path()));
    const auto entryList = pluginsDir.entryList(QDir::Files);
    for (const QString&fileName: entryList) {
        QPluginLoader loader(pluginsDir.absoluteFilePath(fileName));
        QObject*plugin = loader.instance();
        if (plugin)
            addViewer(plugin);
#if 0
        else
            qDebug() << loader.errorString();
#endif
    }
}

Implementación y depuración de complementos

El documento «Implementación de complementos » describe el proceso de implementación de complementos con aplicaciones y su depuración cuando surgen problemas.

Véase también QPluginLoader y QLibrary.

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