#ctx.getVar()

Membaca nilai variabel secara async dari konteks runtime saat ini. Sumber variabel sama dengan resolusi {{ctx.xxx}} di SQL, template, biasanya berasal dari user saat ini, record saat ini, parameter view, konteks popup, dll.

#Skenario Penggunaan

#Definisi Tipe

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

Return Value: Promise<any>, perlu menggunakan await untuk mendapatkan nilai yang sudah di-resolve; mengembalikan undefined saat variabel tidak ada.

Jika meneruskan path yang tidak dimulai dengan ctx., akan melempar error: ctx.getVar(path) expects an expression starting with "ctx.", got: "...".

#Path Variabel Umum

#ctx.getVarInfos()

Mendapatkan informasi struktur variabel yang dapat di-resolve dalam konteks saat ini (tipe, judul, sub-properti, dll.), untuk eksplorasi path yang tersedia. Return value adalah deskripsi statis berbasis meta, tidak termasuk nilai runtime aktual.

#Definisi Tipe

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

Setiap key di return value adalah path variabel, value adalah informasi struktur yang sesuai dengan path tersebut (berisi type, title, properties, dll.).

#Parameter

#Contoh

// Mendapatkan struktur variabel di bawah record (maksimal expand 3 level)
const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });

// Mendapatkan struktur popup.record
const vars = await ctx.getVarInfos({ path: 'popup.record', maxDepth: 3 });

// Mendapatkan struktur variabel tingkat atas yang lengkap (default maxDepth=3)
const vars = await ctx.getVarInfos();

#Perbedaan dengan ctx.getValue

Pada JSField, gunakan getValue/setValue untuk membaca/menulis field ini; gunakan getVar untuk mengakses variabel konteks lain (seperti record, user, formValues).

#Hal yang Perlu Diperhatikan

• path harus dimulai dengan ctx.: seperti ctx.record.id, jika tidak akan melempar error.
• Method async: harus menggunakan await untuk mendapatkan hasil, seperti const id = await ctx.getVar('ctx.record.id').
• Variabel tidak ada: mengembalikan undefined, dapat menggunakan ?? setelah hasil untuk menyetel default value: (await ctx.getVar('ctx.user.nickname')) ?? 'Tamu'.
• Nilai form: ctx.formValues perlu didapatkan melalui await ctx.getVar('ctx.formValues'), tidak diekspos langsung sebagai ctx.formValues. Pada konteks form lebih utamakan ctx.form.getFieldsValue() untuk membaca nilai terbaru secara real-time.

#Contoh

#Mendapatkan ID Record Saat Ini

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

#Mendapatkan Record dalam Popup

const recordId = await ctx.getVar('ctx.popup.record.id');
if (recordId) {
  ctx.message.info(`Record popup saat ini: ${recordId}`);
}

#Membaca Sub-Item Field Array

const roleNames = await ctx.getVar('ctx.user.roles.name');
// Mengembalikan array nama role, seperti ['admin', 'member']

#Menyetel Default Value

// getVar tidak memiliki parameter defaultValue, dapat menggunakan ?? setelah hasil
const userName = (await ctx.getVar('ctx.user.nickname')) ?? 'Tamu';

#Membaca Nilai Field Form

// ctx.formValues sama dengan ctx.form pada skenario form, dapat menggunakan getVar untuk membaca field nested
const status = await ctx.getVar('ctx.formValues.status');
if (status === 'draft') {
  // ...
}

#Membaca Parameter Query URL

const id = await ctx.getVar('ctx.urlSearchParams.id'); // sesuai dengan ?id=xxx

#Eksplorasi Variabel yang Tersedia

// Mendapatkan struktur variabel di bawah record (maksimal expand 3 level)
const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
// vars seperti { 'record.id': { type: 'string', title: 'id' }, ... }

#Terkait

• ctx.getValue() - Mendapatkan nilai field saat ini secara sinkron (hanya JSField/JSItem, dll.)
• ctx.form - Instance form, ctx.form.getFieldsValue() dapat membaca nilai form secara real-time
• ctx.model - Model dalam konteks eksekusi saat ini
• ctx.blockModel - Parent block tempat JS saat ini berada
• ctx.resource - Instance resource dalam konteks saat ini
• {{ctx.xxx}} di SQL / Template - Menggunakan aturan resolusi yang sama dengan ctx.getVar('ctx.xxx')