Excel でのカスタム関数の作成 (プレビュー)Create custom functions in Excel (preview)

開発者は、カスタム関数を使用して関数をアドインの一部として JavaScript で定義することによって、Excel に新しい関数を追加できます。Custom functions enable developers to add new functions to Excel by defining those functions in JavaScript as part of an add-in. ユーザーは Excel 内から、SUM() などの Excel のあらゆるネイティブ関数の場合と同じようにカスタム関数にアクセスできます。Users within Excel can access custom functions just as they would any native function in Excel, such as SUM(). この記事では、Excel でカスタム関数を作成する方法について説明します。This article describes how to create custom functions in Excel.

注意

カスタム関数は、現在、次のプラットフォームで開発者向けのプレビューとして利用できます。Custom functions are currently available in developer preview and are supported on the following platforms:

  • Excel OnlineExcel Online
  • Windows 版 Excel (64 ビット バージョン 1810 以降)。Excel for Windows (version 1810 or later) 現時点で、Windows 版 Excel 32 ビットではすべてのシナリオが使用できるとは限りません。At present, Excel for Windows 32-bit may not work for all scenarios.
  • Excel for Mac (バージョン 13.329 以降)Excel for Mac (version 13.329 or later)

Excel Online でカスタム関数を使用するには、Office 365 サブスクリプションまたは Microsoft アカウントのいずれかを使用してログインします。To use custom functions within Excel Online, login by using either your Office 365 subscription or a Microsoft account.

Windows 版 Excel または Excel for Mac 内でカスタム関数を使用するには、Office 365 サブスクリプションがあり、Office Insider プログラム (Insider レベル -- 旧称 "Insider Fast") に参加しており、このドキュメントで前述した適切な新しいバージョンの Excel を使用している必要があります。To use custom functions within Excel for Windows or Excel for Mac, you must have an Office 365 subscription, join the Office Insider program (Insider level -- formerly called "Insider Fast"), and use a sufficiently recent build of Excel (as specified earlier in this note).

Office 365 サブスクリプションをまだお持ちでない場合は、Office 365 Developer Program に参加することで入手できます。If you don't already have an Office 365 subscription, you can get one by joining the Office 365 Developer Program.

次の図は、エンドユーザーが Excel ワークシートのセルにカスタム関数を挿入する様子を示します。The following illustration shows an end user inserting a custom function into a cell of an Excel worksheet. CONTOSO.ADD42 カスタム関数は、関数への入力パラメーターとしてユーザーが指定した数値のペアに 42 を追加するように設計されています。The CONTOSO.ADD42 custom function is designed to add 42 to the pair of numbers that the user specifies as input parameters to the function.

animated image showing an end user inserting the CONTOSO.ADD42 custom function into a cell of an Excel worksheet

ADD42 カスタム関数は次のコードにより定義されます。The following code defines the ADD42 custom function.

function add42(a, b) {
  return a + b + 42;
}

注意

この記事で後述する「既知の問題」セクションで、カスタム関数の現状の制限事項を記載します。The Known issues section later in this article specifies current limitations of custom functions.

カスタム関数 アドイン プロジェクトのコンポーネントComponents of a custom functions add-in project

Yo Office ジェネレーターを使用して Excel のカスタム関数アドイン プロジェクトを作成する場合、ジェネレーターが作成するプロジェクトに以下のようなファイルが表示されます。If you use the Yo Office generator to create an Excel custom functions add-in project, you'll see the following files in the project that the generator creates:

ファイルFile ファイル形式File format 説明Description
./src/customfunctions.js./src/customfunctions.js
またはor
./src/customfunctions.ts./src/customfunctions.ts
JavaScriptJavaScript
またはor
TypeScriptTypeScript
カスタム関数を定義するコードが含みます。Contains the code that defines custom functions.
./config/customfunctions.json./config/customfunctions.json JSONJSON カスタム関数を定義し、Excel に関数を登録してエンドユーザーが使用できるようにするためのメタデータを含みます。Contains metadata that describes custom functions and enables Excel to register the custom functions and make them available to end users.
./index.html./index.html HTMLHTML カスタム関数を定義する JavaScript ファイルに <script> 参照を提供します。Provides a <script> reference to the JavaScript file that defines custom functions.
./manifest.xml./manifest.xml XMLXML アドイン内のすべてのカスタム関数の名前空間と、この表で前述した JavaScript、JSON、HTML ファイルの位置を指定します。Specifies the namespace for all custom functions within the add-in and the location of the JavaScript, JSON, and HTML files that are listed previously in this table.

次のセクションでは、これらのファイルに関する詳細について説明します。The following sections provide more information about these files.

スクリプト ファイルScript file

スクリプト ファイル (Yo Office ジェネレーターが作成するプロジェクト内の ./src/customfunctions.js または ./src/customfunctions.ts) には、カスタム関数を定義して、カスタム関数の名前を JSON メタデータ ファイルのオブジェクトにマップするコードが含まれています。The script file (./src/customfunctions.js or ./src/customfunctions.ts in the project that the Yo Office generator creates) contains the code that defines custom functions and maps the names of the custom functions to objects in the JSON metadata file.

たとえば、次のコードはカスタム関数 addincrement を定義し、両方の関数の関連付け情報を指定します。For example, the following code defines the custom functions add and increment and then specifies association information for both functions. add 関数は、id プロパティの値が ADD の JSON メタデータ ファイル内のオブジェクトに関連付けられ、increment 関数は、id プロパティの値が INCREMENT のメタデータ ファイル内のオブジェクトに関連付けられます。The add function is associated with the object in the JSON metadata file where the value of the id property is ADD, and the increment function is associated with the object in the metadata file where the value of the id property is INCREMENT. JSON メタデータ ファイル内のオブジェクトへのスクリプト ファイル内関数名の関連付けの詳細については、「カスタム関数のベスト プラクティス」を参照してください。See Custom functions best practices for more information about associating function names in the script file to objects in the JSON metadata file.

function add(first, second){
  return first + second;
}

function increment(incrementBy, callback) {
  var result = 0;
  var timer = setInterval(function() {
    result += incrementBy;
    callback.setResult(result);
  }, 1000);

  callback.onCanceled = function() {
    clearInterval(timer);
  };
}

// associate `id` values in the JSON metadata file to the JavaScript function names
 CustomFunctions.associate("ADD", add);
 CustomFunctions.associate("INCREMENT", increment);

JSON メタデータ ファイルJSON metadata file

カスタム関数のメタデータ ファイル (Yo Office ジェネレーターが作成するプロジェクトでは ./config/customfunctions.json) は、Excel がカスタム関数の登録し、エンドユーザーが利用できるようするために必要な情報を提供します。The custom functions metadata file (./config/customfunctions.json in the project that the Yo Office generator creates) provides the information that Excel requires to register custom functions and make them available to end users. カスタム関数は、ユーザーがアドインを初めて実行するときに登録されます。Custom functions are registered when a user runs an add-in for the first time. その後は、同じユーザーに対しては、(アドインが最初に実行されたワークブック内のみでなく) すべてのワークブック内で利用が可能になります。After that, they are available to that same user in all workbooks (i.e., not only in the workbook where the add-in initially ran.)

ヒント

JSON ファイルをホストするサーバーでは、カスタム関数を Excel Online で正しく作動させるために、CORS を有効に設定する必要があります。Server settings on the server that hosts the JSON file must have CORS enabled in order for custom functions to work correctly in Excel Online.

customfunctions.json の次のコードは、add 関数のメタデータと上述の increment 関数を指定します。The following code in customfunctions.json specifies the metadata for the add function and the increment function that were described previously. このコード サンプルに続く表では、JSON オブジェクト内の個別のプロパティについての詳細情報を提供します。The table that follows this code sample provides detailed information about the individual properties within this JSON object. JSON メタデータ ファイル内の idname 各プロパティーの値の指定に関する詳細については、「カスタム関数のベスト プラクティス」を参照してください。See Custom functions best practices for more information about specifying the value of id and name properties in the JSON metadata file.

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/office-js/custom-functions.schema.json",
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      "description": "Add two numbers",
      "helpUrl": "http://www.contoso.com",
      "result": {
        "type": "number",
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "first",
          "description": "first number to add",
          "type": "number",
          "dimensionality": "scalar"
        },
        {
          "name": "second",
          "description": "second number to add",
          "type": "number",
          "dimensionality": "scalar"
        }
      ]
    },
    {
      "id": "INCREMENT",
      "name": "INCREMENT",
      "description": "Periodically increment a value",
      "helpUrl": "http://www.contoso.com",
      "result": {
          "type": "number",
          "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "increment",
            "description": "Amount to increment",
            "type": "number",
            "dimensionality": "scalar"
        }
    ],
    "options": {
        "cancelable": true,
        "stream": true
      }
    }
  ]
}

次の表は、JSON メタデータ ファイルに通常格納されているプロパティの一覧表示です。The following table lists the properties that are typically present in the JSON metadata file. JSON メタデータ ファイルの詳細については、「カスタム関数のメタデータ」を参照してください。For more detailed information about the JSON metadata file, see Custom functions metadata.

プロパティProperty 説明Description
id 関数の一意の ID です。A unique ID for the function. この ID には、英数字とピリオドしか使用できません。また、設定後に変更してはいけません。This ID can only contain alphanumeric characters and periods and should not be changed after it is set.
name Excel でエンド ユーザーに表示される関数の名前です。Name of the function that the end user sees in Excel. Excel では、この関数名は XML マニフェスト ファイルで指定されているカスタム関数の名前空間でプレフィックスされます。In Excel, this function name will be prefixed by the custom functions namespace that's specified in the XML manifest file.
helpUrl ユーザーがヘルプを要求したときに表示されるページの URL です。URL for the page that is shown when a user requests help.
description 関数について説明します。Describes what the function does. この値は、関数が Excel 内のオートコンプリート メニューで選択された項目となっている場合に、ツールヒントとして表示されます。This value appears as a tooltip when the function is the selected item in the autocomplete menu within Excel.
result 関数が返す情報の種類を定義するオブジェクトです。Object that defines the type of information that is returned by the function. このオブジェクトに関する詳細情報については result を参照してください。For detailed information about this object, see result.
parameters 関数の入力パラメーターを定義する配列です。Array that defines the input parameters for the function. このオブジェクトに関する詳細情報については parameters を参照してください。For detailed information about this object, see parameters.
options Excel で関数を実行する方法とタイミングの一部をユーザーがカスタマイズできます。Enables you to customize some aspects of how and when Excel executes the function. このプロパティの使用方法の詳細については、ストリーム関数および関数のキャンセルを参照してください。For more information about how this property can be used, see Streaming functions and Canceling a function.

マニフェスト ファイルManifest file

カスタム関数 (Yo Office ジェネレーターが作成するプロジェクトでは ./manifest.xml) を定義するアドインの XML マニフェスト ファイルは、アドイン内のすべてのカスタム関数の名前空間と、 JavaScript、JSON、および HTML の場所を指定します。The XML manifest file for an add-in that defines custom functions (./manifest.xml in the project that the Yo Office generator creates) specifies the namespace for all custom functions within the add-in and the location of the JavaScript, JSON, and HTML files. 次の XML マークアップでは、<ExtensionPoint><Resources> カスタム関数を有効にするアドインのマニフェストに含める必要がある要素の例を示します。The following XML markup shows an example of the <ExtensionPoint> and <Resources> elements that you must include in an add-in's manifest to enable custom functions.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">
  <Id>6f4e46e8-07a8-4644-b126-547d5b539ece</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="helloworld"/>
  <Description DefaultValue="Samples to test custom functions"/>
  <Hosts>
    <Host Name="Workbook"/>
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:8081/index.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Workbook">
        <AllFormFactors>
          <ExtensionPoint xsi:type="CustomFunctions">
            <Script>
              <SourceLocation resid="JS-URL"/>
            </Script>
            <Page>
              <SourceLocation resid="HTML-URL"/>
            </Page>
            <Metadata>
              <SourceLocation resid="JSON-URL"/>
            </Metadata>
            <Namespace resid="namespace"/>
          </ExtensionPoint>
        </AllFormFactors>
      </Host>
    </Hosts>
    <Resources>
      <bt:Urls>
        <bt:Url id="JSON-URL" DefaultValue="https://localhost:8081/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://localhost:8081/dist/win32/ship/index.win32.bundle"/>
        <bt:Url id="HTML-URL" DefaultValue="https://localhost:8081/index.html"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="namespace" DefaultValue="CONTOSO"/>
      </bt:ShortStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

注意

Excel の関数は、XML マニフェスト ファイルで指定された名前空間が接頭辞として付加されます。Functions in Excel are prepended by the namespace specified in your XML manifest file. 関数の名前空間は、関数名の前に付けられ、ピリオドで区切られます。A function's namespace comes before the function name and they are separated by a period. 例えば、Excel ワークシートのセル内で、ADD42 関数を呼び出すためには、=CONTOSO.ADD42 と入力します。これは、CONTOSO が名前空間で、ADD42 が JSON ファイルで指定された関数の名前だからです。For example, to call the function ADD42 in the cell of an Excel worksheet, you would type =CONTOSO.ADD42, because CONTOSO is the namespace and ADD42 is the name of the function specified in the JSON file. 名前空間は、会社またはアドインの識別子としての使用を目的としています。The namespace is intended to be used as an identifier for your company or the add-in. 名前空間にはアルファベットとピリオドのみを含めることが出来ます。A namespace can only contain alphanumeric characters and periods.

外部ソースからデータを返す関数Functions that return data from external sources

カスタム関数が外部ソースからデータを取得する場合には、以下のことを実行する必要があります。If a custom function retrieves data from an external source such as the web, it must:

  1. JavaScript Promise を Excel に返します。Return a JavaScript Promise to Excel.

  2. コールバック関数を使用して Promise を最終値で解決します。Resolve the Promise with the final value using the callback function.

カスタム関数は、Excel での最終結果を待つ間、#GETTING_DATA という一時的な結果をセルに表示します。Custom functions display a #GETTING_DATA temporary result in the cell while Excel waits for the final result. ユーザーは、結果を待つ間もワークシートの残りの部分を通常通り操作することができます。Users can interact normally with the rest of the worksheet while they wait for the result.

次のコード例では、getTemperature() カスタム関数が温度計の現在の温度を取得します。 In the following code sample, the getTemperature() custom function retrieves the current temperature of a thermometer. sendWebRequest は、XHR を使用して温度 Web サービスを呼び出す仮想の関数 (ここでは指定なし) であることに留意してください。Note that sendWebRequest is a hypothetical function (not specified here) that uses XHR to call a temperature web service.

function getTemperature(thermometerID){
    return new Promise(function(setResult){
        sendWebRequest(thermometerID, function(data){
            setResult(data.temperature);
        });
    });
}

ストリーミング関数Streaming functions

ストリーム カスタム関数を使用すると、セルに繰り返しデータを長期的に出力でき、ユーザーが再計算を明示的に要求することは特に必要ありません。Streaming custom functions enable you to output data to cells repeatedly over time, without requiring a user to explicitly request data refresh. 以下のコード サンプルは、毎秒ごとに結果に数値を追加するカスタム関数です。The following code sample is a custom function that adds a number to the result every second. このコードについては、次の点に注意してください。Note the following about this code:

  • Excel は、setResult コールバックを使用して自動的に新しい値を表示します。Excel displays each new value automatically using the setResult callback.

  • 2 番目の入力パラメーターの handler は、[オートコンプリート] メニューから関数が選択された場合、Excel のエンドユーザーに表示されません。The second input parameter, handler, is not displayed to end users in Excel when they select the function from the autocomplete menu.

  • onCanceled コールバックは、関数がキャンセルされた場合に実行される関数を定義します。The onCanceled callback defines the function that executes when the function is canceled. すべてのストリーム関数には、このようなキャンセル ハンドラーの実装が必要です。You must implement a cancellation handler like this for any streaming function. 詳細については、「関数をキャンセルする」を参照してください。For more information, see Canceling a function.

function incrementValue(increment, handler){
  var result = 0;
  setInterval(function(){
    result += increment;
    handler.setResult(result);
  }, 1000);

  handler.onCanceled = function(){
    clearInterval(timer);
  }
}

JSON メタデータ ファイルでストリーミング関数にメタデータを指定する場合には、options オブジェクト内のプロパティ"cancelable": true および "stream": true を以下の例のように設定する必要があります。When you specify metadata for a streaming function in the JSON metadata file, you must set the properties "cancelable": true and "stream": true within the options object, as shown in the following example.

{
  "id": "INCREMENT",
  "name": "INCREMENT",
  "description": "Periodically increment a value",
  "helpUrl": "http://www.contoso.com",
  "result": {
    "type": "number",
    "dimensionality": "scalar"
  },
  "parameters": [
    {
      "name": "increment",
      "description": "Amount to increment",
      "type": "number",
      "dimensionality": "scalar"
    }
  ],
  "options": {
    "cancelable": true,
    "stream": true
  }
}

関数をキャンセルするCanceling a function

状況によっては、帯域幅の消費量、作業メモリ、UPC への負荷を軽減するために、ストリーム カスタム関数の実行をキャンセルする必要があります。In some situations, you may need to cancel the execution of a streaming custom function to reduce its bandwidth consumption, working memory, and CPU load. Excel では、次のような状況で関数の実行をキャンセルします。Excel cancels the execution of a function in the following situations:

  • ユーザーが、関数を参照するセルを編集または削除した場合。When the user edits or deletes a cell that references the function.

  • 関数の引数 (入力) の 1 つが変更されたとき。When one of the arguments (inputs) for the function changes. この場合、キャンセルに続いて、関数の新しい呼び出しがトリガーされます。In this case, a new function call is triggered following the cancellation.

  • ユーザーが手動で再計算をトリガーしたとき。When the user triggers recalculation manually. この場合、キャンセルに続いて、関数の新しい呼び出しがトリガーされます。In this case, a new function call is triggered following the cancellation.

関数をキャンセルする機能を有効にするには、JavaScript 関数内にキャンセル ハンドラーを実装し、関数を記述するJSONのメタデータの options オブジェクト内のプロパティ "cancelable": true を指定する必要があります。To enable the ability to cancel a function, you must implement a cancellation handler within the JavaScript function and specify the property "cancelable": true within the options object in the JSON metadata that describes the function. この記事の前のセクションのコード サンプルに、これらの手法の例が示されています。The code samples in the previous section of this article provide an example of these techniques.

状態の保存と共有Saving and sharing state

カスタム関数は、グローバル JavaScript 変数にデータを保存でき、以降の呼び出しで使用することができます。Custom functions can save data in global JavaScript variables, which can be used in subsequent calls. 保存された状態は、関数のすべてのインスタンスが状態を共有できるため、ユーザーが複数のセルに同じカスタム関数を呼び出す場合に便利です。Saved state is useful when users call the same custom function from more than one cell, because all instances of the function can access the state. たとえば、同じ Web リソースへの追加呼び出しを避けるために、呼び出しから返されたデータを Web リソースに保存することができます。For example, you may save the data returned from a call to a web resource to avoid making additional calls to the same web resource.

次のコード サンプルでは、状態をグローバルに保存する温度ストリーミング関数の実装を示します。The following code sample shows an implementation of a temperature-streaming function that saves state globally. このコードについては、次の点に注意してください。Note the following about this code:

  • streamTemperature 関数がセルに表示される温度の値を毎秒更新し、savedTemperatures 変数をデータ ソースとして使用します。The streamTemperature function updates the temperature value that's displayed in the cell every second and it uses the savedTemperatures variable as its data source.

  • streamTemperature はストリーム関数であるため、その関数がキャンセルされたときに実行されるキャンセル ハンドラーを実装します。Because streamTemperature is a streaming function, it implements a cancellation handler that will run when the function is canceled.

  • ユーザーが streamTemperature 関数を Excel の複数のセルから呼び出す場合、streamTemperature 関数は実行のたびに、同じ savedTemperatures 変数からのデータを読み取ります。If a user calls the streamTemperature function from multiple cells in Excel, the streamTemperature function reads data from the same savedTemperatures variable each time it runs.

  • refreshTemperature 関数は、特定の温度計の温度を毎秒読み取り、結果を savedTemperatures 変数に格納します。The refreshTemperature function reads the temperature of a particular thermometer every second and stores the result in the savedTemperatures variable. refreshTemperature 関数は、Excel でエンド ユーザーには公開されないので、JSON ファイルに登録する必要はありません。Because the refreshTemperature function is not exposed to end users in Excel, it does not need to be registered in the JSON file.

var savedTemperatures;

function streamTemperature(thermometerID, handler){
  if(!savedTemperatures[thermometerID]){
    refreshTemperature(thermometerID); // starts fetching temperatures if the thermometer hasn't been read yet
  }

  function getNextTemperature(){
    handler.setResult(savedTemperatures[thermometerID]); // setResult sends the saved temperature value to Excel.
    var delayTime = 1000; // Amount of milliseconds to delay a request by.
    setTimeout(getNextTemperature, delayTime); // Wait 1 second before updating Excel again.

    handler.onCancelled() = function {
      clearTimeout(delayTime);
    }
  }
  getNextTemperature();
}

function refreshTemperature(thermometerID){
  sendWebRequest(thermometerID, function(data){
    savedTemperatures[thermometerID] = data.temperature;
  });
  setTimeout(function(){
    refreshTemperature(thermometerID);
  }, 1000); // Wait 1 second before reading the thermometer again, and then update the saved temperature of thermometerID.
}

データの範囲を使用するWorking with ranges of data

カスタム関数は、データの範囲を入力パラメーターとして受け入れることができ、また、データの範囲を返すこともできます。Your custom function may accept a range of data as an input parameter, or it may return a range of data. JavaScript では、データの範囲は 2 次元配列として表されます。In JavaScript, a range of data is represented as a two-dimensional array.

例えば、関数が Excel に保存されている数値の範囲から 2 番目に大きい値を返すとします。For example, suppose that your function returns the second highest value from a range of numbers stored in Excel. 次の関数は、Excel.CustomFunctionDimensionality.matrix 型の values パラメーターを受け入れます。The following function accepts the parameter values, which is of type Excel.CustomFunctionDimensionality.matrix. なお、この関数の JSON メタデータでは、パラメーターのtypeプロパティをmatrix と設定します。Note that in the JSON metadata for this function, you would set the parameter's type property to matrix.

function secondHighest(values){
  let highest = values[0][0], secondHighest = values[0][0];
  for(var i = 0; i < values.length; i++){
    for(var j = 1; j < values[i].length; j++){
      if(values[i][j] >= highest){
        secondHighest = highest;
        highest = values[i][j];
      }
      else if(values[i][j] >= secondHighest){
        secondHighest = values[i][j];
      }
    }
  }
  return secondHighest;
}

カスタム関数が呼び出したセルを特定するDetermine which cell invoked your custom function

場合によっては、カスタム関数が呼び出したセルのアドレスを取得する必要が生じます。In some cases you'll need to get the address of the cell that invoked your custom function. これは、次の種類のシナリオで役立ちます。This may be useful in the following types of scenarios:

  • 範囲の書式設定: AsyncStorage で情報を格納するキーとしてセル アドレスを使用します。Formatting ranges: Use the cell's address as the key to store information in AsyncStorage. Excel で onCalculated を使用してAsyncStorage からキーを読み込みます。Then, use onCalculated in Excel to load the key from AsyncStorage.
  • キャッシュされた値を表示させる: 関数がオフラインで使用される場合、onCalculated を使用して AsyncStorage に格納されているキャッシュされた値を表示します。Displaying cached values: If your function is used offline, display stored cached values from AsyncStorage using onCalculated.
  • 調整: セル アドレスを使用して元のセルを検出し、処理が発生している場所での調整を行えます。Reconciliation: Use the cell's address to discover an origin cell to help you reconcile where processing is occurring.

セルのアドレスに関する情報は、関数の JSON メタデータ ファイルで requiresAddresstrue とマークされている場合にのみ公開されます。The information about a cell's address is exposed only if requiresAddress is marked as true in the function's JSON metadata file. これの例を次のサンプルに示します。The following sample gives an example of this:

{
   "id": "ADDTIME",
   "name": "ADDTIME",
   "description": "Display current date and add the amount of hours to it designated by the parameter",
   "helpUrl": "http://www.contoso.com",
   "result": {
      "type": "number",
      "dimensionality": "scalar"
   },
   "parameters": [
      {
         "name": "Additional time",
         "description": "Amount of hours to increase current date by",
         "type": "number",
         "dimensionality": "scalar"
      }
   ],
   "options": {
      "requiresAddress": true
   }
}

セルのアドレスを検索するために、スクリプト ファイル (./src/customfunctions.jsまたは ./src/customfunctions.ts) に getAddress 関数を追加する必要があります。In the script file (./src/customfunctions.js or ./src/customfunctions.ts), you'll also need to add a getAddress function to find a cell's address. この関数は、次のサンプルで示される parameter1 のようなパラメーターを受け取ることができます。This function may take parameters, as shown in the following sample as parameter1. 最後のパラメーターは常に invocationContext で、これはJSON メタデータ ファイルで requiresAddresstrue とマークされているときに Excel が返すセルの位置が格納されているオブジェクトのことです。The last parameter will always be invocationContext, an object containing the cell's location that Excel passes down when requiresAddress is marked as true in your JSON metadata file.

function getAddress(parameter1, invocationContext) {
    return invocationContext.address;
}

既定では、getAddress 関数が返す値は次の形式に従います: SheetName!CellNumberBy default, values returned from a getAddress function follow the following format: SheetName!CellNumber. たとえば、ある関数が Expenses という名前のシートのセル B2 から呼び出される場合の戻り値は Expenses!B2 になります。For example, if a function was called from a sheet called Expenses in cell B2, the returned value would be Expenses!B2.

エラーの処理Handling errors

カスタム関数を定義するアドインをビルドする場合は、実行時エラーを考慮して、エラー処理ロジックを含めるようにします。When you build an add-in that defines custom functions, be sure to include error handling logic to account for runtime errors. カスタム関数のエラー処理は、全体的な Excel の JavaScript API のエラー処理と同じです。Error handling for custom functions is the same as error handling for the Excel JavaScript API at large. 次のコード サンプルでは、.catch がコード内で以前に発生したエラーを処理します。In the following code sample, .catch will handle any errors that occur previously in the code.

function getComment(x) {
  let url = "https://www.contoso.com/comments/" + x;

  return fetch(url)
    .then(function (data) {
      return data.json();
    })
    .then((json) => {
      return json.body;
    })
    .catch(function (error) {
      throw error;
    })
}

既知の問題Known issues

  • ヘルプの URL とパラメーターの説明。Excel ではまだ使用されていません。Help URLs and parameter descriptions are not yet used by Excel.
  • カスタム関数は現在、モバイル クライアント用の Excel では使用できません。Custom functions are not currently available on Excel for mobile clients.
  • 揮発性関数 (スプレッドシート内の無関係なデータが変更されたときに自動的に再計算する関数) はまだサポートされていません。Volatile functions (those that recalculate automatically whenever unrelated data changes in the spreadsheet) are not yet supported.
  • Office 365 管理ポータルと AppSource による展開は、まだ有効になっていません。Deployment via the Office 365 Admin Portal and AppSource are not yet enabled.
  • Excel Onlineでのカスタム関数は、一定期間動作していないと、セッション中に停止することがあります。Custom functions in Excel Online may stop working during a session after a period of inactivity. ブラウザーのページを更新 (F5) し、機能を復元するカスタム関数を再入力します。Refresh the browser page (F5) and re-enter a custom function to restore the feature.
  • Windows 版 Excel で複数のアドインが実行されている場合、ワークシートのセル内に #GETTING_DATA という一時的な結果が表示されることがあります。You may see the #GETTING_DATA temporary result within the cell(s) of a worksheet if you have multiple add-ins running on Excel for Windows. その場合には、Excel のウィンドウをすべて閉じ、Excel を再起動します。Close all Excel windows and restart Excel.
  • 今後、カスタム関数向けのデバッグ ツールが利用できるようになる可能性があります。Debugging tools specifically for custom functions may be available in the future. それまでは、F12 開発者ツールを使用して Excel Online をデバッグすることができます。In the meantime, you can debug on Excel Online using F12 developer tools. 詳細については、「カスタム関数のベスト プラクティス」を参照してください。See more details in Custom functions best practices.
  • 32 ビット版の Office 365 December インサイダー バージョン 1901 (ビルド 11128.20000) では、カスタム関数が正常に動作しない可能性があります。In the 32 bit version of the Office 365 December Insiders Version 1901 (Build 11128.20000), Custom Functions may not work properly. https://github.com/OfficeDev/Excel-Custom-Functions/blob/december-insiders-workaround/excel-udf-host.win32.bundle でファイルをダウンロードして、このバグを回避できる場合があります。In some cases you can workaround this bug by downloading the file at https://github.com/OfficeDev/Excel-Custom-Functions/blob/december-insiders-workaround/excel-udf-host.win32.bundle. それから、"C:\Program Files (x86)\Microsoft Office\root\Office16" フォルダーにそれをコピーします。Then, copy it your "C:\Program Files (x86)\Microsoft Office\root\Office16" folder.

関連項目See also