Saltar a contenido

Detalles técnicos de los complementos de QField

Esta página es una colección de API y comportamientos del marco de complementos QField para guiarlo en la escritura de sus propios complementos.

Para ver lo que es posible y obtener inspiración de la comunidad, puede explorar una lista de todos los complementos disponibles en el Tema del complemento QField en GitHub.

Hola mundo QField

La creación de scripts para complementos de QField requiere conocimientos básicos de QML y Javascript. Qt ofrece un tutorial introductorio útil que vale la pena leer.

Una vez que se haya familiarizado con el entorno QML, estará listo para empezar. Este es un ejemplo mínimo que mostrará un mensaje de aviso al cargar correctamente un complemento QField:

import QtQuick
import org.qfield

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

Creación de un complemento comprimido

Un complemento comprimido válido debe contener un archivo main.qml en la raíz del archivo zip, que QField utilizará para activar el complemento. También se puede usar un archivo metadata.txt opcional para proporcionar detalles básicos como el nombre del complemento, una breve descripción y el nombre del autor. Un ejemplo típico de contenido de un archivo metadata.txt sería el siguiente:

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

Este complemento de plantilla QField ofrece un esqueleto simple a partir del cual puedes crear complementos desde cero.

Interfaz iface

Much like QGIS plugins, QField offers an iface object exposing a number of functionalities plugins can leverage. The current invocable functions include:

  • iface.mainWindow(): devuelve la instancia QML ApplicationWindow, donde los complementos pueden vincular sus elementos a través de iface.mainWindow().contentItem y tener acceso a funcionalidades como mostrar mensajes de aviso usando iface.mainWindow().displayToast(text).
  • iface.mapCanvas(): devuelve el elemento del lienzo del mapa, que expone propiedades cruciales, incluido iface.mapCanvas().mapSettings, desde el cual se puede recuperar y modificar la extensión, la escala, etc.
  • iface.findItemByObjectName(string): devuelve un elemento que se encuentra dentro de la ventana de la aplicación QField que coincide con el nombre de objeto string, como iface.findItemByObjectName("positionSource") para llegar al elemento de posicionamiento que controla el dispositivo GNSS y devuelve detalles de posición. Las cadenas de nombres de objetos de elementos adicionales se pueden encontrar viendo el código QML de la ventana de la aplicación.
  • iface.addItemToPluginsToolbar(item), iface.addItemToDashboardActionsToolbar(item), iface.addItemToCanvasActionsToolbar(item): agrega un item determinado en contenedores predefinidos dentro de la ventana de la aplicación QField. El uso de estas funciones garantiza que los elementos agregados por múltiples complementos coexistirán sin problemas.

Objetos de utilidades

QField se entrega con una serie de objetos de utilidad para manipular entidades y geometrías, acceder a capas de mapas, leer y escribir variables de proyectos y capas de mapas, y mucho más.

To familiarize yourself with these, visit QField’s source code’s utilities directory where .h[eader] files will provide documentation for all invocable functions.

Fragmentos de código del complemento

Integración de la barra de búsqueda

El marco del complemento le permite integrar búsquedas personalizadas en la barra de búsqueda de QField a través del elemento QFieldLocatorFilter que se puede agregar al elemento raíz de un complemento:

QFieldLocatorFilter {
  id: locatorFilter

  delay: 1000
  name: "unique_filter_string"
  displayName: "Plugin filter"
  prefix: "plug"
  locatorBridge: iface.findItemByObjectName('locatorBridge')

  parameters: { "parameter_1": "value_1" }
  source: Qt.resolvedUrl('search.qml')

  function triggerResult(result) {
    // result is a QgsLocatorResult object with the following properties:
    // - description, displayString, group, groupScore, score, and userData
  }

  function triggerResultFromAction(result, actionId) {
    // additional actions handled here
  }
}

La propiedad source se refiere a un archivo fuente QML que contendrá la lógica para ejecutar búsquedas y transmitir resultados. Se ejecutará fuera del hilo principal para permitir operaciones de obtención de resultados sin bloqueo.

A continuación se muestra un código fuente QML de búsqueda simple:

import QtQuick
import org.qfield

Item {
  signal prepareResult(var details)
  signal fetchResultsEnded()

  function fetchResults(string, context, parameters) {
    // string is the search term(s) typed into the search bar
    // context is a QgsLocatorContext object with the following properties:
    // - targetExtent, targetExtentCrs, and transformContext
    // parameters is a map of keys and values attached to the QFieldLocatorFilter parameters properties

    // sample details object
    let result_details = {
      "userData": { "key": "value" },
      "displayString": "display string",
      "description": "description",
      "score": 1,
      "group": "group name",
      "groupScore":1,
      "actions":[{"id": 2, "name": "action", "icon": "icon.svg"}]
    }

    // prepareResult is the signal needed to pass on a result
    // you can trigger the signal as many times as you need to pass on all available results
    prepareResult(result_details);
  }
}

Este complemento de nominación QField OpenStreetMap es un buen ejemplo para aprender más sobre la integración de la barra de búsqueda.

Botón de configuración dentro del administrador de complementos

Para los complementos que requieren configuración del usuario, QField permite que estos agreguen un botón de configuración dentro de su administrador de complementos.

To do so, you can simply add a function configure() invocable function attached to the plugin's root item:

import QtQuick
import org.qfield

Item {
  // ...

  function configure()
  {
    optionDialog.open();
  }

  Dialog {
    id: optionDialog
    parent: iface.mainWindow().contentItem
    visible: false
    modal: true
    title: "Configuration"

    // ...
  }
}

Superposición de lienzo para resaltar geometría

Los complementos pueden utilizar el elemento resaltador de geometría de QField para mostrar geometrías creadas o obtenidas a través del siguiente código:

import QtQuick
import org.qfield

Item {
  // ...

  property var geometryHighlighter: iface.findItemByObjectName('geometryHighlighter')

  function demo() {
    // Flash Null Island geometry
    let geom = GeometryUtils.createGeometryFromWkt("POINT(0 0)")
    let crs = CoordinateReferenceSystemUtils.fromDescription("EPSG:4326")

    geometryHighlighter.geometryWrapper.qgsGeometry = geometry
    geometryHighlighter.geometryWrapper.crs = crs;
  }
}