Saltar a contenido

Complementos de QField

QField tiene un marco de complemento QML/Javascript a través del cual se pueden programar funcionalidades y características adicionales.

Tipos de complementos

Los complementos se pueden servir de dos maneras:

  • como un complemento específico del proyecto que estará activo durante la duración de una sesión del proyecto determinado;
  • como un complemento de aplicación que se activará cuando se inicie QField.

Nota

Se muestra un cuadro de diálogo de permiso antes de activar un complemento, brindándole la posibilidad de otorgar o denegar complementos individuales.

Complementos de proyecto

Los complementos de proyecto se despliegan como un archivo sidecar de un archivo de proyecto determinado y deben compartir el mismo nombre de archivo con extensión .qml. nombre de archivo con extensión .qml. Por ejemplo, si su archivo de proyecto es "tree_inventory_qfield.qgs", el archivo QML principal del complemento debe ser "tree_inventory_qfield.qml".

Para los proyectos en la nube, basta con añadir el archivo QML correspondiente en la carpeta local del proyecto en la nube y cargar el archivo recién añadido en QGIS utilizando qfieldsync. Este método asegura un complemento sin problemas y la actualización de los dispositivos en el campo.

Para proyectos que no sean en la nube, consulte la página de documentación de QField storage handling documentation page para aprender a importar proyectos en dispositivos.

Complementos de la aplicación

Los complementos de la aplicación se instalan a través de una ventana emergente de complementos a la que se accede desde el panel Configuración de QField de QField. Basta con pulsar el botón "Instalar complemento desde URL" y pegar una URL que apunte a un archivo de complemento comprimido. archivo comprimido del complemento.

Una vez instalado, el complemento aparecerá en la lista de complementos que se encuentra en la ventana emergente, con un interruptor para activar el complemento.

Autores de complementos

Los complementos QField de scripting requieren conocimientos básicos de QML y Javascript. Qt ofrece un útil tutorial introductorio que merece la pena leer.

Una vez que te hayas familiarizado con el entorno QML, estarás listo para empezar. Este es un ejemplo que mostrará un mensaje de bienvenida al cargar correctamente un complemento QField:

import QtQuick

import org.qfield 1.0
import Theme 1.0

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

Much like QGIS plugins, QField offers an ‘iface’ object exposing a number of functionalities plugins can leverage.

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.

A plugin providing weather forecast as an overlay to QField's map canvas is available in this github repository as a practical example to learn from.

Creating a zipped plugin

A valid zipped plugin must contain a main.qml file at the root of the zip archive, which will be used by QField to activate the plugin. An optional metadata.txt can also be used to provide basic details such as the plugin name, brief description, and author name. A sample typical metadata.txt content would look like this:

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