#ctx.getVar()

Đọc giá trị biến bất đồng bộ từ ngữ cảnh runtime hiện tại. Nguồn biến giống với cách parse {{ctx.xxx}} trong SQL, template, thường đến từ user hiện tại, bản ghi hiện tại, tham số view, ngữ cảnh popup, v.v.

#Kịch bản áp dụng

#Định nghĩa kiểu

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

Giá trị trả về: Promise<any>, cần dùng await để lấy giá trị đã parse; trả về undefined khi biến không tồn tại.

Nếu truyền vào đường dẫn không bắt đầu bằng ctx., sẽ ném lỗi: ctx.getVar(path) expects an expression starting with "ctx.", got: "...".

#Đường dẫn biến thường dùng

#ctx.getVarInfos()

Lấy thông tin cấu trúc (kiểu, tiêu đề, sub-property, v.v.) của các biến có thể parse trong ngữ cảnh hiện tại, tiện cho việc khám phá các đường dẫn khả dụng. Giá trị trả về là mô tả tĩnh dựa trên meta, không chứa giá trị runtime thực tế.

#Định nghĩa kiểu

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

Mỗi key trong giá trị trả về là đường dẫn biến, value là thông tin cấu trúc tương ứng với đường dẫn đó (chứa type, title, properties, v.v.).

#Tham số

#Ví dụ

// 获取 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();

#Khác biệt với ctx.getValue

Trong JSField, đọc/ghi field này dùng getValue/setValue; truy cập biến ngữ cảnh khác (như record, user, formValues) dùng getVar.

#Lưu ý

• path phải bắt đầu bằng ctx.: như ctx.record.id, nếu không sẽ ném lỗi.
• Phương thức bất đồng bộ: phải dùng await để lấy kết quả, như const id = await ctx.getVar('ctx.record.id').
• Biến không tồn tại: trả về undefined, có thể dùng ?? sau kết quả để đặt giá trị mặc định: (await ctx.getVar('ctx.user.nickname')) ?? '访客'.
• Giá trị form: ctx.formValues cần được lấy qua await ctx.getVar('ctx.formValues'), không trực tiếp expose ra ctx.formValues. Trong ngữ cảnh form ưu tiên dùng ctx.form.getFieldsValue() để đọc giá trị mới nhất theo thời gian thực.

#Ví dụ

#Lấy ID bản ghi hiện tại

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

#Lấy bản ghi trong popup

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

#Đọc sub-item của field array

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

#Đặt giá trị mặc định

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

#Đọc giá trị field form

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

#Đọc tham số query của URL

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

#Khám phá biến khả dụng

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

#Liên quan

• ctx.getValue() - Lấy đồng bộ giá trị field hiện tại (chỉ JSField/JSItem, v.v.)
• ctx.form - Instance form, ctx.form.getFieldsValue() có thể đọc giá trị form theo thời gian thực
• ctx.model - Model nơi ngữ cảnh thực thi hiện tại đang nằm
• ctx.blockModel - Block cha nơi JS hiện tại đang nằm
• ctx.resource - Instance resource trong ngữ cảnh hiện tại
• {{ctx.xxx}} trong SQL / template - Sử dụng cùng quy tắc parse với ctx.getVar('ctx.xxx')