連携フィールド（RelationSelect）

連携フィールド（RelationSelect）は、別のアプリのレコードを参照して値を取得するフィールドです。通常配置と明細の列の両方を JavaScript から読み書きできます。

2つの同期タイプ

アプリのフィールド設定「同期タイプ」によって、値の実体が変わります。

同期タイプ	入力方法	値の実体
同期	参照ウィンドウ／サジェストからの選択のみ	`value.value`（連携先キー）＋ `value.label`
非同期	参照で初期値を取り込んだうえで自由入力も可能	`value.viewText`

非同期タイプでは、連携先キーが空のまま、表示テキストだけが入っている状態が正常です。

データ構造

const record = atPocket.app.record.get();
const relation = record['field-3'];

// 同期タイプ
{
  type: 'RelationSelect',
  value: {
    value: 123,             // 連携先レコードのキー
    label: 'A株式会社',      // 表示ラベル（＝保存される値）
    viewText: '',           // 同期タイプでは未使用
    relationId: 5,          // 連携設定ID
  },
  labelValue: 'A株式会社',   // 表示名（@pocket が値から補完します）
  editable: true,
}

// 非同期タイプ（自由入力）
{
  type: 'RelationSelect',
  value: {
    value: null,               // 参照で選んでいない場合は null（正常）
    label: '手入力テキスト',
    viewText: '手入力テキスト',  // 入力値そのもの（＝保存される値）
    relationId: 8,
  },
  labelValue: '手入力テキスト',
  editable: true,
}

参照元が複数選択（チェックボックス・複数選択）の場合は、value.viewText と labelValue が配列になります。

値の設定

キー（value.value）または表示名（labelValue）を設定するだけで連携先が解決され、コピー先のフィールドまで反映されます。解決を指示するフラグは不要です。

const record = atPocket.app.record.get();

record['field-3'].labelValue = 'ABC株式会社';   // 表示名で解決する
// record['field-3'].value.value = '2';        // キーで解決する（同名が複数あっても確実）

await atPocket.app.record.set(record);

非同期タイプでは、入力値を value.viewText で直接読み書きします。連携先のキーと表示テキストを1回の set() で同時に指定することもできます。

const record = atPocket.app.record.get();

record['field-3'].value.value = '4';            // 連携先のキー
record['field-3'].value.viewText = '手入力値';   // 表示テキスト

await atPocket.app.record.set(record);

選択の解除

const record = atPocket.app.record.get();

record['field-3'].value.value = '';   // または record['field-3'].lookup = 'CLEAR';

await atPocket.app.record.set(record);

空の labelValue を設定してもクリアされません。

連携先の検索を明示する（lookup）

labelValue は、同期タイプでは「検索キーワード」、非同期タイプでは「入力テキスト」と意味が変わります。lookup を省略した場合は次のように自動で判定します。

同期タイプ	`lookup` 省略時の動作
同期	`labelValue` が現在の表示名と違えば、連携先を検索します
非同期	連携先を検索せず、`value.viewText` へ転記します

自動判定では表現できない指定は、lookup で明示できます。

値	動作
`'SEARCH'`	`labelValue` で連携先を検索します。同期タイプでは解決済みでも引き直すため、連携元のデータが更新された場合の再取得に使えます
`'NONE'`	`labelValue` では検索しません（表示テキストのみ反映します）。非同期タイプでは省略時と同じ動作です
`'CLEAR'`	連携値とコピー先をクリアします

record['field-3'].labelValue = 'ABC株式会社';
record['field-3'].lookup = 'SEARCH';   // 解決済みでも引き直す
await atPocket.app.record.set(record);

'CLEAR' が最優先です（'SEARCH' / 'NONE' と同時に指定した場合はクリアされます）
キー（value.value）の変更による解決は、'NONE' を指定しても行います。抑止すると「新しいキー＋古い表示名＋古いコピー先」という食い違った値になるためです

明細の連携列

明細の列に配置された連携フィールドも同じ方法で操作できます。表示名だけを指定して新規行を追加でき、複数行をまとめても連携列ごとに1リクエストで解決します。

const record = atPocket.app.record.get();

record['field-6'].value.push({
  value: { 'field-6_3': { labelValue: '顧客-00004' } },
});

await atPocket.app.record.set(record);

注意

明細の連携列は、クリアを含めてすべて非同期です。結果を参照する場合は await してください
明細の列では value.label の直接設定は反映されません。表示名を変更する場合は labelValue を使ってください

解決に失敗したとき

連携先の解決に失敗すると app.record.lookup.error イベントが発火します。

atPocket.events.on('app.record.lookup.error', (event) => {
  const lines = event.errors.map((e) =>
    e.row ? `${e.row.index + 1}行目: ${e.message}` : e.message);
  alert(lines.join('\n'));

  return false;   // 既定のインラインエラー表示を抑止する
});

`reason`	内容	連携値・コピー先
`NOT_FOUND`	該当する連携元レコードがありません	クリアされます
`AMBIGUOUS`	表示名が複数のレコードに一致し、特定できません	クリアされます
`API_FAILED`	通信・サーバの障害で取得できませんでした	維持されます

失敗はコンソールに出力されません

配信されるビルドではコンソール出力が除去されます。解決の失敗を検知するには、このイベントを購読してください。

レコード詳細画面での扱い

注意

レコード詳細画面（app.record.detail.show）では、連携設定を取得できないため連携先の解決を行いません。labelValue は表示テキストの上書きとしてのみ扱われます。

2つの同期タイプ​

データ構造​

値の設定​

選択の解除​

連携先の検索を明示する（lookup）​

明細の連携列​

解決に失敗したとき​

レコード詳細画面での扱い​

関連ページ​