• 简体中文

      • ctx.getVar()

      从当前运行时上下文中异步读取变量值。变量来源与 SQL、模板中的 {{ctx.xxx}} 解析一致，通常来自当前用户、当前记录、视图参数、弹窗上下文等。

      适用场景

      场景说明
      JSBlock / JSField获取当前记录、用户、资源等信息用于渲染或逻辑判断
      联动规则 / 事件流读取 ctx.record、ctx.formValues 等做条件判断
      公式 / 模板与 {{ctx.xxx}} 使用相同的变量解析规则

      类型定义

      getVar(path: string): Promise<any>;
      参数类型说明
      pathstring变量路径，必须以 ctx. 开头，支持点访问与数组下标

      返回值：Promise<any>，需使用 await 获取解析后的值；变量不存在时返回 undefined。

      若传入不以 ctx. 开头的路径，会抛出错误：ctx.getVar(path) expects an expression starting with "ctx.", got: "..."。

      常用变量路径

      路径说明
      ctx.record当前记录（表单/详情绑定记录时可用）
      ctx.record.id当前记录主键
      ctx.formValues当前表单值（联动规则、事件流中常用；表单场景下优先用 ctx.form.getFieldsValue() 实时读取）
      ctx.user当前登录用户
      ctx.user.id当前用户 ID
      ctx.user.nickname当前用户昵称
      ctx.user.roles.name当前用户角色名（数组）
      ctx.popup.record弹窗内记录
      ctx.popup.record.id弹窗内记录主键
      ctx.urlSearchParamsURL 查询参数（从 ?key=value 解析而来）
      ctx.token当前 API Token
      ctx.role当前角色

      ctx.getVarInfos()

      获取当前上下文中可解析变量的结构信息（类型、标题、子属性等），便于探索可用路径。返回值为基于 meta 的静态描述，不包含实际运行值。

      类型定义

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

      返回值中每个 key 为变量路径，value 为该路径对应的结构信息（含 type、title、properties 等）。

      参数

      参数类型说明
      pathstring | string[]剪裁路径，仅收集该路径下的变量结构。支持 'record'、'record.id'、'ctx.record'、'{{ ctx.record }}'；数组表示多个路径合并
      maxDepthnumber最大展开层级，默认 3。不传 path 时顶层属性 depth=1；传 path 时 path 对应节点 depth=1

      示例

      // 获取 record 下的变量结构（最多展开 3 层）
const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });

// 获取 popup.record 的结构
const vars = await ctx.getVarInfos({ path: 'popup.record', maxDepth: 3 });

// 获取完整顶层变量结构（默认 maxDepth=3）
const vars = await ctx.getVarInfos();

      与 ctx.getValue 的区别

      方法适用场景说明
      ctx.getValue()JSField、JSItem 等可编辑字段同步获取当前字段的值，需表单绑定
      ctx.getVar(path)任意 RunJS 上下文异步获取任意 ctx 变量，path 需以 ctx. 开头

      在 JSField 中读写本字段用 getValue/setValue；访问其他上下文变量（如 record、user、formValues）用 getVar。

      注意事项

      • path 必须以 ctx. 开头：如 ctx.record.id，否则抛出错误。
      • 异步方法：必须使用 await 获取结果，如 const id = await ctx.getVar('ctx.record.id')。
      • 变量不存在：返回 undefined，可在结果后使用 ?? 设置默认值：(await ctx.getVar('ctx.user.nickname')) ?? '访客'。
      • 表单值：ctx.formValues 需通过 await ctx.getVar('ctx.formValues') 获取，不直接暴露为 ctx.formValues。在表单上下文中优先用 ctx.form.getFieldsValue() 实时读取最新值。

      示例

      获取当前记录 ID

      const recordId = await ctx.getVar('ctx.record.id');
if (recordId) {
  ctx.message.info(`当前记录：${recordId}`);
}

      获取弹窗内记录

      const recordId = await ctx.getVar('ctx.popup.record.id');
if (recordId) {
  ctx.message.info(`当前弹窗记录：${recordId}`);
}

      读取数组字段子项

      const roleNames = await ctx.getVar('ctx.user.roles.name');
// 返回角色名数组，如 ['admin', 'member']

      设置默认值

      // getVar 无 defaultValue 参数，可在结果后使用 ??
const userName = (await ctx.getVar('ctx.user.nickname')) ?? '访客';

      读取表单字段值

      // ctx.formValues 与 ctx.form 同为表单场景，可用 getVar 读取嵌套字段
const status = await ctx.getVar('ctx.formValues.status');
if (status === 'draft') {
  // ...
}

      读取 URL 查询参数

      const id = await ctx.getVar('ctx.urlSearchParams.id'); // 对应 ?id=xxx

      探索可用变量

      // 获取 record 下的变量结构（最多展开 3 层）
const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
// vars 形如 { 'record.id': { type: 'string', title: 'id' }, ... }

      相关

      • ctx.getValue() - 同步获取当前字段值（仅 JSField/JSItem 等）
      • ctx.form - 表单实例，ctx.form.getFieldsValue() 可实时读取表单值
      • ctx.model - 当前执行上下文所在模型
      • ctx.blockModel - 当前 JS 所在的父区块
      • ctx.resource - 当前上下文中的 resource 实例
      • SQL / 模板中的 {{ctx.xxx}} - 与 ctx.getVar('ctx.xxx') 使用相同解析规则