#ctx.getVar()

Lee de forma asíncrona el valor de una variable desde el contexto de ejecución actual. La resolución de variables es consistente con el análisis de {{ctx.xxx}} en SQL y plantillas, proviniendo generalmente del usuario actual, el registro actual, parámetros de vista, contexto de ventanas emergentes, etc.

#Escenarios de uso

#Definición de tipos

getVar(path: string): Promise<any>;

Valor de retorno: Promise<any>. Debe usar await para obtener el valor resuelto; devuelve undefined si la variable no existe.

Si se pasa una ruta que no comienza con ctx., se lanzará un error: ctx.getVar(path) expects an expression starting with "ctx.", got: "...".

#Rutas de variables comunes

#ctx.getVarInfos()

Obtiene la información estructural (tipo, título, subpropiedades, etc.) de las variables resolubles en el contexto actual, facilitando la exploración de las rutas disponibles. El valor devuelto es una descripción estática basada en meta y no incluye los valores reales de ejecución.

#Definición de tipos

getVarInfos(options?: { path?: string | string[]; maxDepth?: number }): Promise<Record<string, any>>;

En el valor de retorno, cada clave es una ruta de variable y el valor es la información estructural de esa ruta (incluyendo type, title, properties, etc.).

#Parámetros

#Ejemplo

// Obtener la estructura de variables bajo record (expandido hasta 3 niveles)
const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });

// Obtener la estructura de popup.record
const vars = await ctx.getVarInfos({ path: 'popup.record', maxDepth: 3 });

// Obtener la estructura completa de variables de nivel superior (maxDepth=3 por defecto)
const vars = await ctx.getVarInfos();

#Diferencia con ctx.getValue

En un JSField, use getValue/setValue para leer o escribir el campo actual; use getVar para acceder a otras variables de contexto (como record, user, formValues).

#Notas

• La ruta debe comenzar con ctx.: por ejemplo, ctx.record.id, de lo contrario se lanzará un error.
• Método asíncrono: Debe usar await para obtener el resultado, por ejemplo, const id = await ctx.getVar('ctx.record.id').
• Variable inexistente: Devuelve undefined. Puede usar ?? después del resultado para establecer un valor predeterminado: (await ctx.getVar('ctx.user.nickname')) ?? 'Invitado'.
• Valores de formulario: ctx.formValues debe obtenerse mediante await ctx.getVar('ctx.formValues'); no se expone directamente como ctx.formValues. En un contexto de formulario, prefiera usar ctx.form.getFieldsValue() para leer los valores más recientes en tiempo real.

#Ejemplos

#Obtener el ID del registro actual

const recordId = await ctx.getVar('ctx.record.id');
if (recordId) {
  ctx.message.info(`Registro actual: ${recordId}`);
}

#Obtener un registro dentro de una ventana emergente

const recordId = await ctx.getVar('ctx.popup.record.id');
if (recordId) {
  ctx.message.info(`Registro de la ventana emergente actual: ${recordId}`);
}

#Leer subelementos de un campo de tipo arreglo

const roleNames = await ctx.getVar('ctx.user.roles.name');
// Devuelve un arreglo de nombres de roles, p. ej., ['admin', 'member']

#Establecer un valor predeterminado

// getVar no tiene un parámetro defaultValue; use ?? después del resultado
const userName = (await ctx.getVar('ctx.user.nickname')) ?? 'Invitado';

#Leer valores de campos de formulario

// Tanto ctx.formValues como ctx.form son para escenarios de formulario; use getVar para leer campos anidados
const status = await ctx.getVar('ctx.formValues.status');
if (status === 'draft') {
  // ...
}

#Leer parámetros de consulta de la URL

const id = await ctx.getVar('ctx.urlSearchParams.id'); // Corresponde a ?id=xxx

#Explorar variables disponibles

// Obtener la estructura de variables bajo record (expandido hasta 3 niveles)
const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
// vars se ve como { 'record.id': { type: 'string', title: 'id' }, ... }

#Relacionado

• ctx.getValue() - Obtiene de forma síncrona el valor del campo actual (solo JSField/JSItem)
• ctx.form - Instancia del formulario; ctx.form.getFieldsValue() puede leer valores del formulario en tiempo real
• ctx.model - El modelo donde reside el contexto de ejecución actual
• ctx.blockModel - El bloque padre donde se encuentra el JS actual
• ctx.resource - La instancia del recurso en el contexto actual
• {{ctx.xxx}} en SQL / Plantillas - Utiliza las mismas reglas de resolución que ctx.getVar('ctx.xxx')