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

Al igual que los complementos de QGIS, QField ofrece un objeto iface que expone diversas funcionalidades que los complementos pueden aprovechar. Las funciones invocables actuales incluyen:

  • 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.

Para familiarizarse con estos, visite el directorio de utilidades del código fuente de QField, donde los archivos .h[eader] proporcionarán documentación para todas las funciones invocables.

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 es el término o términos de búsqueda escritos en la barra de búsqueda
    // context es un objeto QgsLocatorContext con las siguientes propiedades:
    // - targetExtent, targetExtentCrs, y transformContext
    // parámetros son un mapa de claves y valores adjuntos a las propiedades de los parámetros de QFieldLocatorFilter

    // objeto de detalles de muestra
    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 es la señal necesaria para transmitir un resultado
    // puede activar la señal tantas veces como necesite para transmitir todos los resultados disponibles
    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.

Para hacer esto, simplemente puede agregar una función invocable function configure() adjunta al elemento raíz del complemento:

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;
  }
}