同期カスタム関数 (プレビュー)

同期カスタム関数を使用すると、評価と条件付き書式の処理をカスタム関数と同時に Excel で実行できます。 カスタム関数をこの記事に記載されている Excel プロセスのいずれかと並行して実行する必要がある場合は、同期サポートを有効にします。 同期操作をサポートしていないカスタム関数は、これらの Excel プロセスと同時に実行すると、 #CALC! や #VALUE! などのエラーを返します。

同期カスタム関数でサポートされる Excel プロセス

次のアクションとプロセスは、同期カスタム関数と連携します。

サポートされている評価アクション

• Excel で数式を選択し、[数式を評価する] を選択します。
• Excel で [数式]、[関数の挿入] の順に選択します。
• セル編集モードで、数式の一部を選択して F9 キーを押すと、部分的な計算結果が表示されます。
• VBA の Application.Calculate メソッド。

サポートされている条件付き書式操作

次の一覧は、Excel UI API と Office JavaScript API の両方によってトリガーされる条件付き書式設定アクションに適用されます。

• 新しいルールを作成します。
• ルールを編集します。
• ルールの削除。
• 規則を並べ替えます。
• "適用対象" の範囲を変更します。
• "条件を満たす場合は停止" のオンとオフを切り替えます。
• すべてのルールをクリアします。
• 条件付き書式を含むセルを切り取って貼り付ける。
• 条件付き書式を含むセルをコピーして貼り付ける。

アドインで同期サポートを有効にする

アドインで同期シナリオをサポートするには、次の手順を実行します。

• JSON メタデータを自動生成する場合は、@supportSync JSDoc タグを使用します。
• JSON メタデータを手動で作成する場合は、functions.json ファイルの "options" オブジェクトの "supportSync": true 設定を使用します。
• 関数で Excel.RequestContext を使用している場合は、Excel.RequestContext の setInvocation メソッドを呼び出して、CustomFunctions.Invocation オブジェクトを渡します。 例については、 コード例を参照してください。

コード サンプル

次のコード サンプルは、同期カスタム関数を作成する方法を示しています。

/** 
 * A synchronous custom function that takes a cell address and returns the value of that cell.
 * @customfunction
 * @supportSync
 * @param {string} address The address of the cell from which to retrieve the value.
 * @param {CustomFunctions.Invocation} invocation Invocation object.
 * @returns The value of the cell at the input address.
 */ 
export async function getCellValue(address, invocation) {
  const context = new Excel.RequestContext();
  context.setInvocation(invocation); // The `invocation` object must be passed in the `setInvocation` method for synchronous functions.

  const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
  range.load("values");

  await context.sync(); 
  return range.values[0][0];
}

関連項目

• カスタム関数用の JSON メタデータの自動生成
• カスタム関数の JSON メタデータを手動で作成する