#ctx.getVar()

現在の実行コンテキストから変数の値を非同期で読み取ります。変数のソースは SQL やテンプレート内の {{ctx.xxx}} の解析ルールと一致しており、通常は現在のユーザー、現在のレコード、ビューのパラメータ、ポップアップのコンテキストなどから取得されます。

#適用シーン

#型定義

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

戻り値: Promise<any>。解析後の値を取得するには await を使用する必要があります。変数が存在しない場合は undefined を返します。

ctx. で始まらないパスを渡すと、エラーがスローされます：ctx.getVar(path) expects an expression starting with "ctx.", got: "..."。

#よく使われる変数のパス

#ctx.getVarInfos()

現在のコンテキストで解析可能な変数の構造情報（型、タイトル、子プロパティなど）を取得し、利用可能なパスを確認しやすくします。戻り値は meta に基づく静的な記述であり、実際の実行時の値は含まれません。

#型定義

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

戻り値の各キーは変数のパスであり、値はそのパスに対応する構造情報（type、title、properties などを含む）です。

#パラメータ

#実行例

// 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 との違い

JSフィールド内で自身のフィールドを読み書きする場合は getValue/setValue を使用し、他のコンテキスト変数（record、user、formValues など）にアクセスする場合は getVar を使用します。

#注意事項

• パスは必ず 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() - 現在のフィールド値を同期的に取得（JSフィールド/JSアイテムなど限定）
• ctx.form - フォームインスタンス。ctx.form.getFieldsValue() でフォームの値をリアルタイムに読み取り可能
• ctx.model - 現在の実行コンテキストが属するモデル
• ctx.blockModel - 現在の JS が配置されている親ブロック
• ctx.resource - 現在のコンテキストにおけるリソースインスタンス
• SQL / テンプレート内の {{ctx.xxx}} - ctx.getVar('ctx.xxx') と同じ解析ルールを使用します