Apps operativas

Apps operativas: vistas

Cómo componer las pantallas de una app operativa: vistas, secciones, el catálogo de componentes con sus propiedades y los componentes propios.

Actualizado: 2026-11-17

En esta guía

Cómo se arma una pantalla

Una app tiene una lista de vistas. Cada vista tiene secciones y cada sección tiene componentes. No escribes interfaz: eliges componentes del catálogo y los configuras con props.

{
  "viewId": "returns-detail",
  "name": "Devolución",
  "kind": "detail",
  "recordTypeId": "returns.request",
  "version": 1,
  "status": "published",
  "layout": {
    "sections": [
      {
        "id": "summary",
        "title": "Resumen",
        "columns": 1,
        "components": [
          { "id": "fields", "type": "record-detail", "fieldIds": ["orderNumber", "storeId", "amount", "reason"] },
          { "id": "decide", "type": "actions", "actionIds": ["approve", "reject"], "props": { "primaryActionId": "approve" } }
        ]
      },
      {
        "id": "evidence",
        "title": "Comprobantes",
        "components": [{ "id": "receipts", "type": "files", "props": { "slotIds": ["receipt"] } }]
      }
    ]
  }
}

Vistas

  • viewId, name: identificador y título. El panel lista las vistas de la app en el orden en que las declaras.
  • kind: table, queue, overview, automation, form o detail. Una vista detail necesita un registro seleccionado; las demás trabajan sobre la lista.
  • recordTypeId: el tipo de registro que carga la vista. El panel trae los registros de ese tipo que el usuario puede leer.
  • actionIds: acciones que aplican a los componentes de la vista que no nombran las suyas.
  • context.createCapability: capacidad necesaria para ver el botón de crear registro. Si no la declaras, lo ve todo el que puede abrir la app.

Dos comportamientos que conviene conocer:

  • La app se abre en la primera vista cuyo kind no sea detail ni form.
  • Al hacer clic en una fila de una tabla, el panel selecciona el registro y abre la primera vista detail del mismo tipo de registro.

Cada vista carga hasta 100 registros, filtrados por el buscador. Las métricas y los gráficos de registros se calculan sobre esos registros cargados. Para totales sobre volúmenes mayores, usa un dataset.

Secciones

  • id, title: identificador y encabezado.
  • columns: de 1 a 4. Los componentes se reparten en esa cuadrícula.
  • components: la lista de componentes.

Lo que todo componente acepta

  • id: único dentro de la vista.
  • type: el componente del catálogo.
  • title: título, cuando el componente lo muestra.
  • fieldIds: campos que usa el componente, en orden.
  • actionIds: acciones que ofrece.
  • props: configuración propia del componente.
  • visibleWhen: { "field": "reason", "equals": "defective" } o notEquals. Se evalúa contra los datos del registro seleccionado. Sin registro seleccionado, el componente se muestra.

Un type que no existe no rompe la pantalla: se muestra una nota en su lugar.

Catálogo de componentes

Registros

  • table / queue: tabla de registros con su estado. fieldIds define las columnas (por defecto, los seis primeros campos del esquema). props.titleField elige el campo que titula cada fila.
  • record-detail / status: campos del registro seleccionado, con el origen de cada dato cuando existe. fieldIds (por defecto, los diez primeros).
  • form: formulario generado desde el esquema. fieldIds limita los campos; los campos readOnly nunca se ofrecen. props.mode: create (por defecto) o edit. props.capability: capacidad necesaria para verlo.
  • metric: una cifra sobre los registros cargados. props.aggregate: count o sum. props.field: campo que suma. props.where: { "state": ["requested"], "data": { "storeId": ["store-01", "store-02"] } }. props.format y props.accent (blue, amber, emerald, rose) ajustan la presentación.
  • chart: barras con la cantidad de registros por estado. props.states (por defecto, los del ciclo de vida) y props.limit (por defecto 3).
  • activity: historial del registro seleccionado.
  • relationship: relaciones del registro seleccionado con otros registros.
  • evidence / artifacts: evidencias enlazadas al registro seleccionado.
  • source-rows: filas de origen del registro. props.inlineField (por defecto sourceRows), props.relationshipTypes, props.recordTypeIds, props.fieldIds, props.sources.
  • execution-state: estado de ejecución leído del registro. props.stateField (por defecto executionState) y props.executionIdField (por defecto executionId).
  • agent-plan: texto de plan leído de props.field (por defecto agentPlan).
  • text: texto fijo en props.text, o el valor del campo props.field.

Acciones

  • actions / action: botones para las acciones del registro seleccionado. actionIds (o props.actionIds) limita cuáles; props.primaryActionId marca la principal. Si la acción declara input, se abre un formulario; si declara requiresConfirmation, se pide confirmación.
  • collection-actions: lo mismo para acciones de colección. No necesita registro.

Archivos

  • files: zona de subida, lista y descarga. props.slotIds elige las ranuras. Sin esa propiedad muestra las ranuras de la app y, con un registro abierto, las de su tipo.

Datasets

  • dataset-table: tabla paginada. props.datasetId (obligatorio). fieldIds o props.fieldIds define las columnas. props.filterFieldIds define los filtros (por defecto, los campos enum). props.pageSize (por defecto 25).
  • dataset-chart: barras agrupadas. props.datasetId (obligatorio), props.labelField (por defecto, el primer campo de la clave), props.valueField, props.aggregate: sum para sumar valueField, o cuenta filas si no lo indicas. props.limit (por defecto 12). Lee hasta 500 filas.

Propios

  • custom:<componentId>: un componente tuyo, declarado en customComponents.

Visibilidad según permisos

El panel oculta lo que el usuario no puede hacer y el servidor lo vuelve a comprobar en cada petición:

  • Una acción solo aparece si el servidor la devolvió como disponible para ese registro: el usuario tiene la capacidad, el registro está en su alcance y el estado lo permite.
  • Una ranura de archivos no se ofrece si falta su capacidad.
  • Un form con props.capability no se muestra si falta esa capacidad.
  • El botón de crear registro respeta context.createCapability.

No existe una propiedad genérica de capacidad para cualquier componente. Para ocultar una sección entera a un rol, apóyate en estos puntos o separa el contenido en otra app.

Componentes propios

Cuando el catálogo no alcanza, puedes mostrar una página tuya dentro de una vista.

{
  "customComponents": [
    { "componentId": "refund-calculator", "label": "Calculadora de reembolso", "url": "https://apps.example.com/refund-calculator", "height": 420 }
  ]
}

Luego la usas como { "id": "calculator", "type": "custom:refund-calculator" }.

La página la alojas y la mantienes tú. Quantum la carga en un marco aislado y le pasa contexto por mensajes.

El protocolo

Tu página envía a la ventana contenedora:

  • { "type": "qac.ready" }: lista para recibir contexto. Sin este mensaje no llega nada.
  • { "type": "qac.resize", "height": 520 }: pide una altura en píxeles, entre 80 y 4000.
  • { "type": "qac.action", "actionId": "approve", "input": { "note": "..." } }: pide ejecutar una acción de la app.

Tu página recibe:

  • { "type": "qac.context", "app": { "appId": "...", "settings": {} }, "record": {}, "locale": "es" }: llega después de qac.ready y cada vez que cambian el registro, la configuración o el idioma. record es null si no hay registro seleccionado.
  • { "type": "qac.action.result", "actionId": "approve", "ok": true }: resultado de la acción pedida. Si falla, ok es false y llega error.
<script>
  window.addEventListener("message", (event) => {
    if (event.source !== window.parent) return;
    const message = event.data || {};
    if (message.type === "qac.context") {
      render(message.record, message.app.settings, message.locale);
      window.parent.postMessage({ type: "qac.resize", height: document.body.scrollHeight }, "*");
    }
    if (message.type === "qac.action.result") {
      showResult(message.ok, message.error);
    }
  });

  function approve(note) {
    window.parent.postMessage({ type: "qac.action", actionId: "approve", input: { note } }, "*");
  }

  window.parent.postMessage({ type: "qac.ready" }, "*");
</script>

Qué puede hacer el marco y qué no

Puede:

  • Leer el registro seleccionado, la configuración de la app y el idioma.
  • Pedir una acción declarada en la app. Se ejecuta con la identidad y los permisos del usuario, con el input que envías. Si la acción declara requiresConfirmation, el usuario confirma antes.
  • Ejecutar scripts y enviar formularios dentro de su propio marco.

No puede:

  • Recibir el token de sesión ni llamar a la API de Quantum como el usuario.
  • Leer o modificar la página del panel.
  • Abrir ventanas emergentes ni navegar la ventana principal.
  • Usar cookies o almacenamiento local de su propio dominio: el marco se carga sin origen propio.
  • Ejecutar algo que no sea una acción declarada. Los permisos se comprueban en el servidor.

Tres reglas para tu página:

  • La url debe ser https.
  • Comprueba event.source === window.parent antes de confiar en un mensaje.
  • No guardes secretos en settings: la configuración llega al marco y a todo el que puede abrir la app.