Singletons en QML
En QML, un singleton es un objeto que se crea como máximo una vez por engine. En esta guía, explicaremos cómo crear singletons y cómo utilizarlos. También ofreceremos algunas prácticas recomendadas para trabajar con singletons.
¿Cómo se pueden crear singletons en QML?
Hay dos formas distintas de crear singletons en QML. Puedes definir el singleton en un archivo QML o registrarlo desde C++.
Definición de singletons en QML
Para definir un singleton en QML, primero tienes que añadir
pragma Singletonal principio del archivo. Hay un paso más: tendrás que añadir una entrada al archivo qmldir del módulo QML.
Uso de qt_add_qml_module (CMake)
Al utilizar CMake, qt_add_qml_module crea automáticamente el archivo qmldir. Para indicar que el archivo QML debe convertirse en un singleton, hay que establecer la propiedad QT_QML_SINGLETON_TYPE del mismo:
set_source_files_properties(MySingleton.qml
PROPERTIES QT_QML_SINGLETON_TYPE TRUE)Se pueden pasar varios archivos a la vez a ` set_source_files_properties`:
set(plain_qml_files
MyItem1.qml
MyItem2.qml
FancyButton.qml
)
set(qml_singletons
MySingleton.qml
MyOtherSingleton.qml
)
set_source_files_properties(${qml_singletons}
PROPERTIES QT_QML_SINGLETON_TYPE TRUE)
qt_add_qml_module(myapp
URI MyModule
QML_FILES ${plain_qml_files} ${qml_singletons}
)Nota: es necesario llamar a `set_source_files_properties ` antes de qt_add_qml_module
Sin `qt_add_qml_module`
Si no utilizas ` qt_add_qml_module`, tendrás que crear manualmente un archivo `qmldir`. En él, deberás marcar tus singletons como corresponde:
module MyModule
singleton MySingleton 1.0 MySingleton.qml
singleton MyOtherSingleton 1.0 MyOtherSingleton.qmlConsulta también «Declaración de tipos de objetos » para obtener más detalles.
Definición de singletons en C++
Existen varias formas de exponer singletons a QML desde C++. La principal diferencia radica en si se debe crear una nueva instancia de una clase cuando el motor QML la necesite, o si es necesario exponer un objeto ya existente a un programa QML.
Registro de una clase para proporcionar singletons
La forma más sencilla de definir un singleton es disponer de una clase con constructor por defecto, derivada de ` QObject `, y marcarla con las macros ` QML_SINGLETON ` y ` QML_ELEMENT `.
class MySingleton : public QObject
{
Q_OBJECT
QML_SINGLETON
QML_ELEMENT
public:
MySingleton(QObject *parent = nullptr) : QObject(parent) {
// ...
}
};Esto registrará la clase ` MySingleton ` con el nombre ` MySingleton ` en el módulo QML al que pertenece el archivo. Si deseas exponerla con un nombre diferente, puedes utilizar ` QML_NAMED_ELEMENT ` en su lugar.
Si no es posible hacer que la clase sea constructible por defecto, o si necesitas acceder al objeto ` QQmlEngine ` en el que se instancia el singleton, es posible utilizar en su lugar una función `create` estática. Debe tener la firma ` MySingleton *create(QQmlEngine *, QJSEngine *)`, donde ` MySingleton ` es el tipo de la clase que se registra.
class MyNonDefaultConstructibleSingleton : public QObject
{
Q_OBJECT
QML_SINGLETON
QML_NAMED_ELEMENT(MySingleton)
public:
MyNonDefaultConstructibleSingleton(QJSValue id, QObject *parent = nullptr)
: QObject(parent)
, m_symbol(std::move(id))
{}
static MyNonDefaultConstructibleSingleton *create(QQmlEngine *qmlEngine, QJSEngine *)
{
return new MyNonDefaultConstructibleSingleton(qmlEngine->newSymbol(u"MySingleton"_s));
}
private:
QJSValue m_symbol;
};Nota: La función `create` toma como parámetros tanto un ` QJSEngine ` como un ` QQmlEngine `. Esto se debe a razones históricas. Ambos apuntan al mismo objeto, que de hecho es un ` QQmlEngine`.
Exponer un objeto instanciado en C++ como un singleton
Puede resultar útil controlar la instanciación de un singleton desde C++, en lugar de dejar que el ` QQmlEngine ` instancie la instancia. Estos singletons no necesitan ser instanciables por el motor, por lo que puedes prescindir de un constructor por defecto o de una función estática ` create `. Si lo haces, debes incluir la macro ` QML_UNCREATABLE ` en la declaración del singleton:
class MyNonDefaultConstructibleSingleton : public QObject
{
Q_OBJECT
QML_SINGLETON
QML_NAMED_ELEMENT(MySingleton)
QML_UNCREATABLE("Provided by C++")
public:
MyNonDefaultConstructibleSingleton(BackendObject* backend, QObject *parent = nullptr)
: QObject(parent)
, m_backend(backend)
{}
private:
class BackendObject* backend;
};A continuación, configuramos la instancia que se va a utilizar en el motor, antes de iniciarlo:
MyNonDefaultConstructibleSingleton singleton(backend);
QQmlApplicationEngine engine;
engine.setExternalSingletonInstance("MyModule", "MySingleton", &singleton);
engine.loadFromModule("MyModule", "Main");Exponer un objeto existente como singleton
A veces, se dispone de un objeto ya existente que puede haber sido creado a través de alguna API de terceros. A menudo, la opción más adecuada en este caso es disponer de un único singleton que exponga dichos objetos como sus propiedades (véase Agrupar datos relacionados). Pero si ese no es el caso, por ejemplo, porque solo hay un único objeto que debe exponerse, utiliza el siguiente enfoque para exponer al motor una instancia de tipo ` MySingleton `. Primero exponemos el singleton como un ` foreign type`:
struct SingletonForeign
{
Q_GADGET
QML_FOREIGN(MySingleton)
QML_SINGLETON
QML_NAMED_ELEMENT(MySingleton)
QML_UNCREATABLE("Provided from C++")
};A continuación, simplemente instanciamos el `MySingleton` y lo asignamos al motor:
MySingleton instance = getSingletonInstance();
QQmlApplicationEngine engine;
engine.setExternalSingletonInstance("MyModule", "MySingleton", &instance);
engine.loadFromModule("MyModule", "Main");Nota: En este caso,puede resultar muy tentador utilizar simplemente ` qmlRegisterSingletonInstance `. Sin embargo, hay que tener cuidado con los riesgos del registro imperativo de tipos que se enumeran en la siguiente sección.
Registro imperativo de tipos
Antes de Qt 5.15, todos los tipos, incluidos los singletons, se registraban a través de la API qmlRegisterType. Los singletons, en concreto, se registraban mediante qmlRegisterSingletonType o qmlRegisterSingletonInstance. Además de la pequeña molestia de tener que repetir el nombre del módulo para cada tipo y de la separación forzada entre la declaración de la clase y su registro, el principal problema de ese enfoque era que resultaba poco compatible con las herramientas: No era posible, de forma estática, extraer toda la información necesaria sobre los tipos de un módulo en tiempo de compilación. El registro declarativo resolvió este problema.
Nota: Queda un caso de uso para la API imperativa qmlRegisterType: es una forma de exponer un singleton de un tipo noQObject como una propiedad var mediante the QJSValue based qmlRegisterSingletonType overload . Es preferible la alternativa: exponer ese valor como propiedad de un singleton basado en (QObject), de modo que la información de tipo esté disponible.
Acceso a los singletons
Se puede acceder a los singletons tanto desde QML como desde C++. En QML, es necesario importar el módulo que los contiene. A continuación, se puede acceder al singleton mediante su nombre. La lectura y escritura de sus propiedades en contextos de JavaScript se realiza de la misma forma que con los objetos normales:
import QtQuick
import MyModule
Item {
x: MySingleton.posX
Component.onCompleted: MySingleton.ready = true;
}No es posible configurar enlaces en las propiedades de un singleton; sin embargo, si fuera necesario, se puede utilizar un elemento ` Binding ` para lograr el mismo resultado:
import QtQuick
import MyModule
Item {
id: root
Binding {
target: MySingleton
property: "posX"
value: root.x
}
}Nota: Hay que tenercuidado al establecer un enlace en una propiedad de un singleton: si lo hace más de un archivo, los resultados no están definidos.
Directrices para (no) utilizar singletons
Los singletons permiten exponer al motor datos a los que se debe acceder desde varios lugares. Pueden ser ajustes compartidos globalmente, como el espaciado entre elementos, o modelos de datos que deben mostrarse en varios lugares. En comparación con las propiedades de contexto, que pueden resolver un caso de uso similar, tienen la ventaja de estar tipados, de ser compatibles con herramientas como el QML Language Server, y, por lo general, son más rápidos en tiempo de ejecución.
Se recomienda no registrar demasiados singletons en un módulo: los singletons, una vez creados, permanecen activos hasta que se destruye el propio motor y presentan los inconvenientes del estado compartido, ya que forman parte del estado global. Por lo tanto, considera utilizar las siguientes técnicas para reducir la cantidad de singletons en tu aplicación:
Agrupar datos relacionados
Añadir un singleton por cada objeto que quieras exponer genera bastante código repetitivo. La mayoría de las veces, tiene más sentido agrupar los datos que quieres exponer como propiedades de un único singleton. Supongamos, por ejemplo, que quieres crear un lector de libros electrónicos en el que necesitas exponer tres abstract item models: uno para libros locales y dos para fuentes remotas. En lugar de repetir tres veces el proceso para exponer los objetos existentes, puedes crear un único singleton y configurarlo antes de iniciar la aplicación principal:
class GlobalState : QObject
{
Q_OBJECT
QML_ELEMENT
QML_SINGLETON
Q_PROPERTY(QAbstractItemModel* localBooks MEMBER localBooks)
Q_PROPERTY(QAbstractItemModel* digitalStoreFront MEMBER digitalStoreFront)
Q_PROPERTY(QAbstractItemModel* publicLibrary MEMBER publicLibrary)
public:
QAbstractItemModel* localBooks;
QAbstractItemModel* digitalStoreFront;
QAbstractItemModel* publicLibrary
};
int main() {
QQmlApplicationEngine engine;
auto globalState = engine.singletonInstance<GlobalState *>("MyModule", "GlobalState");
globalState->localBooks = getLocalBooks();
globalState->digitalStoreFront = setupLoalStoreFront();
globalState->publicLibrary = accessPublicLibrary();
engine.loadFromModule("MyModule", "Main");
}Utilizar instancias de objetos
En la última sección, vimos el ejemplo de exponer tres modelos como miembros de un singleton. Esto puede resultar útil cuando los modelos deben utilizarse en varios lugares o cuando los proporciona una API externa sobre la que no tenemos control. Sin embargo, si solo necesitamos los modelos en un único lugar, podría tener más sentido tenerlos como un tipo instanciable. Volviendo al ejemplo anterior, podemos añadir una clase RemoteBookModel instanciable y, a continuación, instanciarla dentro del archivo QML del explorador de libros:
// remotebookmodel.h
class RemoteBookModel : public QAbstractItemModel
{
Q_OBJECT
QML_ELEMENT
Q_PROPERTY(QUrl url READ url WRITE setUrl NOTIFY urlChanged)
// ...
};// bookbrowser.qml
Row {
ListView {
model: RemoteBookModel { url: "www.public-lib.example"}
}
ListView {
model: RemoteBookModel { url: "www.store-front.example"}
}
}Pasar el estado inicial
Aunque los singletons pueden utilizarse para pasar el estado a QML, resultan un desperdicio cuando el estado solo se necesita para la configuración inicial de la aplicación. En ese caso, a menudo es posible utilizar un « QQmlApplicationEngine::setInitialProperties ». Por ejemplo, quizá quieras establecer Window::visibility en modo de pantalla completa si se ha activado el indicador de línea de comandos correspondiente:
QQmlApplicationEngine engine;
if (parser.isSet(fullScreenOption)) {
// assumes root item is ApplicationWindow
engine.setInitialProperties(
{ "visibility", QVariant::fromValue(QWindow::FullScreen)}
);
}
engine.loadFromModule("MyModule, "Main");
© 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.