カスタム関数で数式値プレビュー モードを操作する

数式値プレビュー モードに参加するときに、カスタム関数で結果を計算する方法を制御できます。 数式値プレビュー モードは、エンド ユーザーがセルの編集中に数式の一部を選択して値をプレビューできるようにする機能です。 この機能は、ユーザーが編集時に数式を評価するのに役立ちます。 次の図は、ユーザーが数式を編集し、テキスト A1+A2を選択する例を示しています。 数式プレビュー モードには、上記の 7 値が表示されます。

既定では、ユーザーがカスタム関数 ( =getHousePrice(A1)など) をプレビューできます。 ただし、次の一覧は、カスタム関数が数式値プレビュー モードにどのように参加するかを制御するシナリオをいくつか示しています。

• カスタム関数は、使用料金を請求する 1 つ以上の API を呼び出します。
• カスタム関数は、データベースなどの 1 つ以上の希少なリソースにアクセスします。
• カスタム関数は結果の計算にかなりの時間がかかり、プレビューの目的ではユーザーには役に立ちません。

代わりにモック値を返すようにカスタム関数の動作を変更できます。 これを行うには、 invocation.isInValuePreview の読み取り専用プロパティを使用します。 次のコード サンプルは、収益化された API を使用して住宅価格を検索する getHousePrice という名前のカスタム関数の例を示しています。 isInValuePreviewがtrueされている場合、カスタム関数は使用するモック番号を返し、コストの発生を回避します。 isInValuePreviewがfalseの場合、カスタム関数は API を呼び出し、Excel スプレッドシートで使用する実際の住宅価格の値を返します。

/**
 * Get the listing price for a house on the market for the given address.
 * @customfunction
 * @param address The address of the house.
 * @param invocation Custom function handler.
 * @returns The price of the house at the address.
 */
export function getHousePrice(address: string, invocation: CustomFunctions.Invocation): number {
  // Check if this call is for formula value preview mode.
  if (invocation.isInValuePreview) { 
    // Avoid long-running expensive service calls. 
    // Return a useable but fake number.
    return 450000; 
  } else { 
    // Make the actual service calls in this block. 
    const price = callHouseServiceAPI(address);
    return price; 
  } 
}

関連項目

• Excel でカスタム関数を作成する