Les extensions QField¶

QField a un cadriciel d'extension QML/Javascript à travers duquel des fonctionnalités supplémentaires peuvent être écrites.

Types d'extension¶

Les extensions peuvent servir de deux manières :

en tant qu'extension spécifique à un projet et qui sera active durant la session d'un projet donné ;
en tant qu'extension d'application qui sera activée au lancement de QField.

Note

Une boîte de dialogue est affichée avant l'activation d'une extension, vous offrant la possibilité d'accorder ou de refuser des droits à chaque extension.

Les extensions de projet¶

Les extensions de projets sont déployées comme un fichier "side-car" d'un fichier de projet donné et doivent partager le même nom de fichier avec une extension de fichier .qml. Par exemple, si votre fichier de projet s'appelle “tree_inventory_qfield.qgs”, le fichier QML principal de l'extension doit se nommer “tree_inventory_qfield.qml”.

Pour les projets cloud, ajoutez simplement le fichier QML concerné dans le répertoire local de votre projet cloud et téléversez le fichier nouvellement ajouté via QGIS en utilisant qfieldsync. Cette méthode assure un déploiement sans problème de l'extension et la mise-à-jour des appareils sur le terrain.

Pour les projets hors-cloud, se référer à la page de documentation sur les manipulations de stockage de QField pour savoir comment importer les projets sur les périphériques.

Les extensions d'application¶

Les extensions d'application sont installées via une fenêtre pop-up d'extension à partir du panneau des Paramètres de QField. Simplement presser le bouton ‘installer l'extension à partir de l'URL’ et y coller une URL pointant vers un fichier d'extension compressé.

Une fois installée, l'extension apparaîtra dans la liste des extensions située dans la fenêtre pop-up, avec une possibilité de sélectionner l'activation ou non de l'extension.

Écriture d'une extension¶

Écrire des extensions QField requiert des connaissances basiques en QML et Javascript. Qt offre un tutoriel d'initiation utile et d'une lecture profitable.

Une fois que vous vous êtes familiarisé avec l'environnement QML, vous êtes prêt à démarrer. Voici un exemple minimal qui affichera une notification dès qu'une extension QField sera chargée avec succès :

import QtQuick

import org.qfield 1.0
import Theme 1.0

Item {
  Component.onCompleted: {
    iface.mainWindow().displayToast('Hello world!')
  }
}

De manière très similaire aux extensions QGIS, QField offre un objet ‘iface’ présentant de nombreuses fonctionnalités que les extensions peuvent exploiter.

The iface.mainWindow() function points at the QML ApplicationWindow instance, where plugins can parent their popups and items via iface.mainWindow().contentItem and have access to functionality such as displaying toast messages using iface.mainWindow().displayToast(text).

The iface.mapCanvas() function provides access to the map canvas item and its properties, including the crucial iface.mapCanvas().mapSettings object where the extent, scale, etc. can be retrieved and modified. It can also be used to parent items as overlays to the map canvas.

The iface.findItemByObjectName() function allows plugins to access items with QField’s application window through a matching object name. You can see these items by viewing the relevant source code.

In addition, several iface functions allow plugins to harmoniously add elements within the QField interface: iface.addItemToPluginsToolbar(item), iface.addItemToMainMenuActionsToolbar(item), and iface.addItemToCanvasActionsToolbar(item). Using these functions insure that items added by multiple plugins will happily co-exist.

In addition a number of utility classes are available to plugin authors allowing for project layer fetching, vector layer editing, and more. To familiarize yourself with these, visit QField’s source code’s utilities classes directory.

Une extension fournissant les prévisions météorologiques sous la forme d'une surcouche du canevas de carte de QField est disponible dans ce dépôt github à titre d'exemple concret d'apprentissage.

Créer une extension zippée¶

Une extension zippée valide doit contenir un fichier main.qml à la racine de l'archive zip, qui sera utilisée par QField pour activer l'extension. Un optionnel metadata.txt peut aussi être utilisé pour fournir des éléments de base tel que le nom de l'extension, une brève description ou le nom de l'auteur. Un échantillon typique de contenu de metadata.txt pourrait ressembler à ceci :

[general]
name=Hello World Plugin
description=This is simple and brief description.
author=OPENGIS.ch
icon=logo.svg