#ctx.getVar()

Lê valores de variáveis do contexto de execução atual de forma assíncrona. A resolução de variáveis é consistente com a de {{ctx.xxx}} em SQL e templates, geralmente originada do usuário atual, registro atual, parâmetros de visualização, contexto de popups, etc.

#Casos de Uso

#Definição de Tipo

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

Valor de Retorno: Promise<any>. Use await para obter o valor resolvido; retorna undefined se a variável não existir.

Se for passado um caminho que não comece com ctx., um erro será lançado: ctx.getVar(path) expects an expression starting with "ctx.", got: "...".

#Caminhos de Variáveis Comuns

#ctx.getVarInfos()

Obtém as informações estruturais (tipo, título, subpropriedades, etc.) das variáveis resolvíveis no contexto atual, facilitando a exploração dos caminhos disponíveis. O valor de retorno é uma descrição estática baseada em meta e não inclui valores reais de execução.

#Definição de Tipo

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

No valor de retorno, cada chave é um caminho de variável e o valor são as informações estruturais para esse caminho (incluindo type, title, properties, etc.).

#Parâmetros

#Exemplo

// Obtém a estrutura da variável sob record (expandida em até 3 níveis)
const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });

// Obtém a estrutura de popup.record
const vars = await ctx.getVarInfos({ path: 'popup.record', maxDepth: 3 });

// Obtém a estrutura completa das variáveis de nível superior (padrão maxDepth=3)
const vars = await ctx.getVarInfos();

#Diferença para ctx.getValue

Em um JSField, use getValue/setValue para ler/escrever no campo atual; use getVar para acessar outras variáveis de contexto (como record, user, formValues).

#Observações

• O caminho deve começar com ctx.: por exemplo, ctx.record.id, caso contrário, um erro será lançado.
• Método assíncrono: Você deve usar await para obter o resultado, por exemplo, const id = await ctx.getVar('ctx.record.id').
• Variável não existe: Retorna undefined. Você pode usar ?? após o resultado para definir um valor padrão: (await ctx.getVar('ctx.user.nickname')) ?? 'Visitante'.
• Valores do formulário: ctx.formValues deve ser recuperado via await ctx.getVar('ctx.formValues'); ele não é exposto diretamente como ctx.formValues. No contexto de um formulário, prefira usar ctx.form.getFieldsValue() para ler os valores mais recentes em tempo real.

#Exemplos

#Obter ID do Registro Atual

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

#Obter Registro Dentro de um Popup

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

#Ler Subitens de um Campo de Array

const roleNames = await ctx.getVar('ctx.user.roles.name');
// Retorna um array de nomes de funções, ex: ['admin', 'member']

#Definir Valor Padrão

// getVar não possui um parâmetro defaultValue; use ?? após o resultado
const userName = (await ctx.getVar('ctx.user.nickname')) ?? 'Visitante';

#Ler Valores de Campos de Formulário

// Tanto ctx.formValues quanto ctx.form são para cenários de formulário; use getVar para ler campos aninhados
const status = await ctx.getVar('ctx.formValues.status');
if (status === 'draft') {
  // ...
}

#Ler Parâmetros de Consulta da URL

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

#Explorar Variáveis Disponíveis

// Obtém a estrutura da variável sob record (expandida em até 3 níveis)
const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
// vars se parece com { 'record.id': { type: 'string', title: 'id' }, ... }

#Relacionados

• ctx.getValue() - Obtém o valor do campo atual de forma síncrona (apenas JSField/JSItem)
• ctx.form - Instância do formulário, ctx.form.getFieldsValue() pode ler valores do formulário em tempo real
• ctx.model - O modelo onde o contexto de execução atual reside
• ctx.blockModel - O bloco pai onde o JS atual está localizado
• ctx.resource - A instância de recurso (resource) no contexto atual
• {{ctx.xxx}} em SQL / Templates - Usa as mesmas regras de resolução que ctx.getVar('ctx.xxx')