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,formodetail. Una vistadetailnecesita 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
kindno seadetailniform. - Al hacer clic en una fila de una tabla, el panel selecciona el registro y abre la primera vista
detaildel 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" }onotEquals. 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.fieldIdsdefine las columnas (por defecto, los seis primeros campos del esquema).props.titleFieldelige 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.fieldIdslimita los campos; los camposreadOnlynunca se ofrecen.props.mode:create(por defecto) oedit.props.capability: capacidad necesaria para verlo.metric: una cifra sobre los registros cargados.props.aggregate:countosum.props.field: campo que suma.props.where:{ "state": ["requested"], "data": { "storeId": ["store-01", "store-02"] } }.props.formatyprops.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) yprops.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 defectosourceRows),props.relationshipTypes,props.recordTypeIds,props.fieldIds,props.sources.execution-state: estado de ejecución leído del registro.props.stateField(por defectoexecutionState) yprops.executionIdField(por defectoexecutionId).agent-plan: texto de plan leído deprops.field(por defectoagentPlan).text: texto fijo enprops.text, o el valor del campoprops.field.
Acciones
actions/action: botones para las acciones del registro seleccionado.actionIds(oprops.actionIds) limita cuáles;props.primaryActionIdmarca la principal. Si la acción declarainput, se abre un formulario; si declararequiresConfirmation, 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.slotIdselige 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).fieldIdsoprops.fieldIdsdefine las columnas.props.filterFieldIdsdefine los filtros (por defecto, los camposenum).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:sumpara sumarvalueField, o cuenta filas si no lo indicas.props.limit(por defecto 12). Lee hasta 500 filas.
Propios
custom:<componentId>: un componente tuyo, declarado encustomComponents.
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
formconprops.capabilityno 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 deqac.readyy cada vez que cambian el registro, la configuración o el idioma.recordesnullsi no hay registro seleccionado.{ "type": "qac.action.result", "actionId": "approve", "ok": true }: resultado de la acción pedida. Si falla,okesfalsey llegaerror.
<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
inputque envías. Si la acción declararequiresConfirmation, 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
urldebe serhttps. - Comprueba
event.source === window.parentantes 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.