qt_target_qml_sources

Fügt QML-Dateien und Ressourcen zu einem bestehenden QML-Modul-Ziel hinzu.

Dieser Befehl wurde in Qt 6.2 eingeführt.

Der Befehl ist in der Komponente „ Qml “ des Pakets „ Qt6 “ definiert, das wie folgt geladen werden kann:

find_package(Qt6 REQUIRED COMPONENTS Qml)

Übersicht

qt_target_qml_sources(
    target
    [QML_FILES ...]
    [RESOURCES ...]
    [PREFIX resource_path]
    [OUTPUT_TARGETS out_targets_var]
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_QMLDIR_TYPES]
)

Wenn versionlose Befehle deaktiviert sind, verwenden Sie stattdessen „ qt6_target_qml_sources() “. Dieser Befehl unterstützt dieselben Argumente wie der vorliegende Befehl.

Beschreibung

qt_target_qml_sources() bietet die Möglichkeit, einem QML-Modul weitere Dateien hinzuzufügen, nachdem ` qt_add_qml_module() ` aufgerufen wurde. Normalerweise übergeben Sie die Sammlung von „ .qml “-Dateien und Ressourcen direkt an `qt_add_qml_module()`, doch in manchen Fällen kann es wünschenswert oder sogar notwendig sein, Dateien hinzuzufügen, nachdem `qt_add_qml_module()` bereits aufgerufen wurde. Beispielsweise möchten Sie möglicherweise Dateien bedingt hinzufügen, basierend auf einem Ausdruck in einer ` if `-Anweisung, oder aus Unterverzeichnissen, die nur hinzugefügt werden, wenn bestimmte Kriterien erfüllt sind. Vielleicht möchten Sie eine Reihe von Dateien hinzufügen, die sich in bestimmten Merkmalen von den anderen unterscheiden, wie z. B. ein anderes Ressourcenpräfix, oder bei denen Linting und Bytecode-Kompilierung deaktiviert sind. Der Befehl ` qt_target_qml_sources() ` ermöglicht diese Szenarien.

Argumente

Das „ target “ muss das zugrunde liegende Ziel eines QML-Moduls sein; falls das QML-Modul kein separates zugrunde liegendes Ziel hat, muss es das Plugin-Ziel des Moduls sein.

QML_FILES ist eine Liste von „ .qml “-Dateien, „ .js “-Dateien und „ .mjs “-Dateien, die dem QML-Modul hinzugefügt werden sollen. Diese Option hat genau denselben Effekt wie die Option „ QML_FILES “ des Befehls ` qt_add_qml_module()`, einschließlich der automatischen Kompilierung zu Bytecode und der Lint-Prüfung.

Die Optionen „ NO_CACHEGEN “ und „ NO_LINT “ haben ebenfalls dieselbe Wirkung wie bei „qt_add_qml_module()“. Sie deaktivieren die Bytecode-Kompilierung und die Lint-Prüfung für die mit „ QML_FILES “ aufgeführten Dateien. Dieses Verhalten kann auch nur für einzelne Dateien mithilfe der Eigenschaften der Quelldateien festgelegt werden.

NO_QMLDIR_TYPES Verhindert, dass die „ QML_FILES “ als Typen zur generierten qmldir-Datei hinzugefügt werden.

RESOURCES hat genau denselben Effekt wie die Option „ RESOURCES “ des Befehls ` qt_add_qml_module() `. Sie liefert eine Liste von Dateien, die als gewöhnliche Ressourcen zum ` target ` hinzugefügt werden sollen. Bei diesen Dateien handelt es sich typischerweise um Bilder, Shader usw., auf die der QML-Code in irgendeiner Weise verweist.

Dateien, die über „ QML_FILES “ oder „ RESOURCES “ zum Modul hinzugefügt werden, werden unter demselben Ressourcenpräfix und Zielpfad abgelegt, als wären sie mit dem Befehl ` qt_add_qml_module()` hinzugefügt worden. Dies kann durch die Angabe eines anderen Speicherorts mit der Option „ PREFIX “ überschrieben werden. Der Wert, der auf das Schlüsselwort „ PREFIX “ folgt, wird direkt verwendet, ohne dass ein Zielpfad angehängt wird. Der endgültige Ressourcenpfad jeder Datei setzt sich aus dem Präfix und dem Pfad der Datei unterhalb von „ CMAKE_CURRENT_SOURCE_DIR “ zusammen. Die Eigenschaft „QT_RESOURCE_ALIAS“ der Quelldatei kann ebenfalls verwendet werden, um diesen relativen Pfad zu überschreiben.

qt_add_qml_module(backing
    URI Example
    VERSION 1.0
    RESOURCE_PREFIX /my.company.com/imports
)

qt_target_qml_sources(backing
    QML_FILES special/First.qml
    RESOURCES icons/logo.png
)

qt_target_qml_sources(backing
    PREFIX /other.company.com/debugging
    QML_FILES Inspector.qml
)

Im obigen Beispiel haben die Ressourcen des Ziels „ backing “ letztendlich folgenden Inhalt:

• /my.company.com/imports/Example/special/First.qml
• /my.company.com/imports/Example/icons/logo.png
• /other.company.com/debugging/Inspector.qml

OUTPUT_TARGETS entspricht ebenfalls der entsprechenden Option für `qt_add_qml_module()`. Verwenden Sie diese Option, um den Namen einer Variablen anzugeben, in der zusätzliche Ziele gespeichert werden sollen, die für statische Builds erstellt wurden. Wenn das „ target “ installiert wird, müssen diese zusätzlichen Ziele ebenfalls installiert werden, um die Anforderungen an die Verknüpfung zu erfüllen.

Eigenschaften der Quelldatei

Eine Reihe von Eigenschaften von Quelldateien kann verwendet werden, um zu beeinflussen, wie jede einzelne „ .qml “-Datei an verschiedenen Stellen bei der Verarbeitung des QML-Moduls behandelt wird. Diese Eigenschaften überschreiben alle übergeordneten Optionen, die bei Aufrufen von ` qt_target_qml_sources() ` oder `qt_add_qml_module()` angegeben wurden. Alle diese Eigenschaften müssen festgelegt werden, bevor die Dateien mit einem dieser beiden Befehle hinzugefügt werden.

QT_QML_SKIP_QMLLINT kann für eine Quelldatei auf ` TRUE ` gesetzt werden, um zu verhindern, dass sie in die automatische qmllint-Verarbeitung einbezogen wird. Standardmäßig werden alle ` .qml `-Dateien in den Lint-Lauf des Ziels einbezogen, aber mit dieser Option können bestimmte Dateien ausgeschlossen werden.

QT_QML_SKIP_CACHEGEN hat eine ähnliche Funktion und verhindert, dass eine Quelldatei zu Bytecode kompiliert wird, wenn diese Eigenschaft auf „ TRUE “ gesetzt ist. Beachten Sie, dass die Datei dennoch in unkompilierter Form als Ressource zum „ target “ hinzugefügt wird (siehe Zwischenspeichern kompilierter QML-Quellen).

Setzen Sie die Eigenschaft „ QT_QML_SKIP_QMLDIR_ENTRY “ der Quelldatei auf „ TRUE “, um zu verhindern, dass diese QML- oder JavaScript-Datei als Typ zur Datei „ qmldir “ des QML-Moduls hinzugefügt wird (siehe Automatische Generierung von „ qmldir “- und „typeinfo“-Dateien). Dies wird normalerweise für eine Datei verwendet, die keinen öffentlichen Typ offenlegt, wie beispielsweise eine private JavaScript-Datei. Für JavaScript-Dateien mit Namen in Großbuchstaben, die weder ECMAScript-Module sind noch über ` .pragma library ` als zustandslose Bibliotheken deklariert wurden, sollten Sie diese Option in Betracht ziehen. Wenn Sie sie in die Datei ` qmldir ` aufnehmen, werden sie im Geltungsbereich jedes QML-Dokuments neu ausgewertet, das das Modul, zu dem sie gehören, explizit oder implizit importiert.

Standardmäßig wird bei der Generierung der Datei „ qmldir “ für jede „ .qml “-Datei, die einen Typ bereitstellt, ein einzelner Typeneintrag generiert. Dieser erhält eine Versionsnummer nach dem Muster „ X.0 “, wobei „ X “ die Hauptversion des QML-Moduls ist. Wenn für das QML-Modul „ PAST_MAJOR_VERSIONS “ festgelegt sind, wird dasselbe Muster auch auf diese angewendet, wobei für jede frühere Hauptversion „ X.0 “ angehängt wird: „ X “. In Fällen, in denen eine Datei stattdessen Typeneinträge für eine andere Gruppe von Versionen bereitstellen muss (z. B. wenn sie erstmals in einer Nebenversion nach der Veröffentlichung von „ .0 “ hinzugefügt wurde), geben Sie diese Versionen in der Eigenschaft „ QT_QML_SOURCE_VERSIONS “ der Quelldatei an. Für jede Version wird ein Typeneintrag erstellt.

Wenn der von einer „ .qml “-Datei bereitgestellte Typ ein Singleton ist, setzen Sie deren Eigenschaft „ QT_QML_SINGLETON_TYPE “ auf „ TRUE “. Ebenso kann die Eigenschaft „ QT_QML_INTERNAL_TYPE “ der Datei auf „ TRUE “ gesetzt werden, um anzugeben, dass es sich bei dem bereitgestellten Typ um einen internen Typ handelt. Der Name des Typs selbst kann ebenfalls mithilfe der Eigenschaft „ QT_QML_SOURCE_TYPENAME “ überschrieben werden. Alle drei Angaben werden in den Typeneinträgen der Datei in der generierten „ qmldir “-Datei widergespiegelt. Die „source“-Eigenschaften müssen vor dem Erstellen des Moduls, zu dem das Singleton gehört, festgelegt werden.

Alle Dateien, die unter QML_FILES oder RESOURCES aufgeführt sind, werden den Ressourcen des target hinzugefügt. Ihr Speicherort in den Ressourcen besteht aus einem Basispunkt und einem relativen Pfad. Der Basispunkt ist standardmäßig die Verkettung des Ressourcenpräfixes des QML-Moduls und seines Zielpfads, kann jedoch mit dem Argument PREFIX überschrieben werden. Der relative Pfad ist standardmäßig der Pfad der Datei relativ zur Ziel-Eigenschaft „ SOURCE_DIR “ des „ target “. Dieser relative Pfad kann durch Setzen der Eigenschaft „ QT_RESOURCE_ALIAS “ in der Quelldatei überschrieben werden. Dies wird häufig verwendet, um Dateien aus verschiedenen Verzeichnissen zu sammeln und sie in den Ressourcen unter einem gemeinsamen Speicherort anzuzeigen. Seit Qt 6.8 ist die Aktivierung von QTP0004 jedoch oft die bessere Option, wenn das Ziel darin besteht, dass alle Dateien des QML-Moduls im impliziten Import gefunden werden können. In Fällen, in denen eine solche manuelle Konfiguration weiterhin erforderlich ist, empfiehlt es sich, „ NO_GENERATE_EXTRA_QMLDIRS “ an „ qt_add_qml_module “ zu übergeben, da die zusätzlichen „qmldirs“ die Alias-Zuordnungen von Ressourcendateien nicht berücksichtigen.

set_source_files_properties(nested/way/down/File.qml PROPERTIES
    QT_RESOURCE_ALIAS File.qml
)
set_source_files_properties(TemplateFile.qml PROPERTIES
    QT_RESOURCE_ALIAS templates/File.qml
    QT_QML_SKIP_QMLDIR_ENTRY TRUE
    QT_QML_SKIP_QMLLINT TRUE
    QT_QML_SKIP_CACHEGEN TRUE
)
set_source_files_properties(FunnySingleton.qml PROPERTIES
    QT_QML_SINGLETON_TYPE TRUE
)
qt_add_qml_module(qt_target_qml_sources_example
    URI Example
    VERSION 2.3
    RESOURCE_PREFIX /my.company.com/imports
    NO_GENERATE_EXTRA_QMLDIRS
    QML_FILES
        nested/way/down/File.qml
        TemplateFile.qml
        FunnySingleton.qml
)

set_source_files_properties(some_old_thing.qml PROPERTIES
    QT_QML_SOURCE_VERSIONS "1.1;2.0"
    QT_QML_SOURCE_TYPENAME OldThing
)
set_source_files_properties(../../../images/button-types.png PROPERTIES
    QT_RESOURCE_ALIAS button-types.png
)
qt_target_qml_sources(qt_target_qml_sources_example
    QML_FILES some_old_thing.qml
    RESOURCES
        ../../../images/button-types.png
        doc/README.txt
)

Im obigen Beispiel werden die Ressourcen des Ziels „ qt_target_qml_sources_example “ letztendlich den folgenden Inhalt haben:

• /my.company.com/imports/Example/File.qml
• /my.company.com/imports/Example/FunnySingleton.qml
• /my.company.com/imports/Example/templates/File.qml
• /my.company.com/imports/Example/some_old_thing.qml
• /my.company.com/imports/Example/button-types.png
• /my.company.com/imports/Example/doc/README.txt

Die generierte Datei „ qmldir “ enthält die folgenden Typeneinträge:

File 2.0 File.qml
singleton FunnySingleton 2.0 FunnySingleton.qml
OldThing 1.1 some_old_thing.qml
OldThing 2.0 some_old_thing.qml

pragma Singleton
import QtQml

QtObject {}