チュートリアル: Excel でのカスタム関数の作成Tutorial: Create custom functions in Excel

カスタム関数では、関数をアドインの一部として JavaScript で定義することによって、Excel に新しい関数を追加できます。Custom functions enable you 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 as they would any native function in Excel, such as SUM(). 計算のような単純なタスク、または Web からワークシートへのデータのリアルタイム ストリーミングのようなより複雑なタスクを実行するカスタム関数を作成できます。You can create custom functions that perform simple tasks like calculations or more complex tasks such as streaming real-time data from the web into a worksheet.

このチュートリアルの内容:In this tutorial, you will:

  • Office アドイン用の Yeoman ジェネレーターを使用して、カスタム関数アドインを作成します。Create a custom function add-in using the Yeoman generator for Office Add-ins.
  • あらかじめ用意されているカスタム関数を使用し、単純な計算を実行します。Use a prebuilt custom function to perform a simple calculation.
  • Web からデータを取得するカスタム関数を作成します。Create a custom function that gets data from the web.
  • Web からデータをリアルタイムでストリーミングするカスタム関数を作成します。Create a custom function that streams real-time data from the web.

前提条件Prerequisites

  • Node.js (バージョン 8.0.0 以降)Node.js (version 8.0.0 or later)

  • GitGit

  • 最新バージョンの YeomanOffice アドイン用の Yeoman ジェネレーター。これらのツールをグローバルにインストールするには、コマンド プロンプトから次のコマンドを実行します。The latest version of Yeoman and the Yeoman generator for Office Add-ins. To install these tools globally, run the following command via the command prompt:

    npm install -g yo generator-office
    

    注意

    以前に一度使用したバージョンのジェネレーターをインストールしていた場合でも、パッケージを npm から最新バージョンに更新することをお勧めします。Even if you've previously installed the Yeoman generator, we recommend you update your package to the latest version from npm.

  • Windows 上の Excel (バージョン1904以降、Office 365 サブスクリプションに接続されている) または webExcel on Windows (version 1904 or later, connected to Office 365 subscription) or on the web

カスタム関数プロジェクトを作成するCreate a custom functions project

まず、カスタム関数アドインをビルドするコード プロジェクトを作成します。To start, you'll create the code project to build your custom function add-in. Office アドイン用の [ごみ箱] ジェネレーターでは、プロジェクトに事前に用意されているカスタム関数を使用してセットアップし、試すことができます。カスタム関数のクイックスタートを既に実行してプロジェクトを生成した場合は、そのプロジェクトを引き続き使用して、この手順に進んでください。The Yeoman generator for Office Add-ins will set up your project with some prebuilt custom functions that you can try out. If you have already run the custom functions quick start and generated a project, continue to use that project and skip to this step instead.

重要

現在、アドインプロジェクトの名前またはアドインプロジェクトを作成するフォルダーパス内の任意の場所にスペースは使用できません。Spaces are not currently permitted in the add-in project name or anywhere in the folder path where you create your add-in project. アドインのプロジェクト名またはフォルダーのパスにスペースが含まれている場合、またはnpm start npm run start:webを実行してもローカル web サーバーは開始されません。If your add-in's project name or folder path contains spaces, the local web server won't start when you run npm start or npm run start:web. この制限は一時的なものであり、元の問題が Office アドイン用のごみ箱のジェネレーターで解決されると削除されます。This limitation is temporary and will be eliminated when the underlying issue is resolved in the Yeoman generator for Office Add-ins.

  1. 次のコマンドを実行し、以下のようにプロンプトに応答します。Run the following command and then answer the prompts as follows.

    yo office
    
    • Choose a project type: (プロジェクトの種類を選択) Excel Custom Functions Add-in projectChoose a project type: Excel Custom Functions Add-in project
    • Choose a script type: (スクリプトの種類を選択) JavaScriptChoose a script type: JavaScript
    • What would you want to name your add-in?: (アドインの名前を何にしますか)What do you want to name your add-in? starcount

    カスタム関数の Office アドイン用の Yeoman ジェネレーターのプロンプト

    Yeoman ジェネレーターはプロジェクト ファイルを作成し、サポートしているノード コンポーネントをインストールします。The Yeoman generator will create the project files and install supporting Node components.

  2. プロジェクトのルート フォルダーに移動します。Navigate to the root folder of the project.

    cd starcount
    
  3. プロジェクトをビルドします。Build the project.

    npm run build
    

    注意

    開発の最中でも、OfficeアドインはHTTPではなくHTTPSを使用する必要があります。Office Add-ins should use HTTPS, not HTTP, even when you are developing. npm run buildの実行後に証明書をインストールするように指示が出された場合は、Yeomanジェネレーターが提供する証明書をインストールする手順に従ってください。If you are prompted to install a certificate after you run npm run build, accept the prompt to install the certificate that the Yeoman generator provides.

  4. Node.js で実行しているローカル Web サーバーを開始します。Start the local web server, which runs in Node.js. Web または Windows 上の Excel でカスタム関数アドインを試すことができます。You can try out the custom function add-in in Excel on the web or Windows.

Windows または Mac 上の Excel でアドインをテストするには、次のコマンドを実行します。To test your add-in in Excel on Windows or Mac, run the following command. このコマンドを実行すると、ローカル web サーバーが起動し、アドインが読み込まれた状態で Excel が開きます。When you run this command, the local web server will start and Excel will open with your add-in loaded.

npm run start:desktop

あらかじめ用意されているカスタム関数を試すTry out a prebuilt custom function

作成したカスタム関数プロジェクトには、 /src/functions/functions.jsファイル内で定義されたあらかじめ用意されたカスタム関数がいくつか含まれています。The custom functions project that you created contains some prebuilt custom functions, defined within the ./src/functions/functions.js file. ./manifest.xml ファイルによって、カスタム関数はすべて CONTOSO 名前空間に属することが指定されます。The ./manifest.xml file specifies that all custom functions belong to the CONTOSO namespace. Excel でカスタム関数にアクセスするには、CONTOSO 名前空間を使用します。You'll use the CONTOSO namespace to access the custom functions in Excel.

その後、次の手順を実行し、ADD カスタム関数を試します。Next you'll try out the ADD custom function by completing the following steps:

  1. Excel で、任意のセルに移動し、=CONTOSO と入力します。In Excel, go to any cell and enter =CONTOSO. CONTOSO 名前空間にあるすべての関数がオートコンプリート メニューに一覧表示されます。Notice that the autocomplete menu shows the list of all functions in the CONTOSO namespace.

  2. セル内で値 =CONTOSO.ADD(10,200) を入力して Enter キーを押し、入力パラメーターとして数値 10200 を指定して、CONTOSO.ADD 関数を実行します。Run the CONTOSO.ADD function, with numbers 10 and 200 as input parameters, by typing the value =CONTOSO.ADD(10,200) in the cell and pressing enter.

ADD カスタム関数によって、指定した 2 つの数字の合計が計算され、210 という結果が返されます。The ADD custom function computes the sum of the two numbers that you provided and returns the result of 210.

Web からデータを要求するカスタム関数を作成するCreate a custom function that requests data from the web

Web からデータを統合することは、カスタム関数を使用して Excel を拡張する優れた方法です。Integrating data from the Web is a great way to extend Excel through custom functions. 次に、指定された Github getStarCountリポジトリのスター数を示すという名前のカスタム関数を作成します。Next you’ll create a custom function named getStarCount that shows how many stars a given Github repository possesses.

  1. Starcountプロジェクトで、 /src/functions/functions.jsを見つけて、コードエディターで開きます。In the starcount project, find the file ./src/functions/functions.js and open it in your code editor.

  2. 関数 .jsで、次のコードを追加します。In function.js, add the following code:

/**
  * Gets the star count for a given Github repository.
  * @customfunction 
  * @param {string} userName string name of Github user or organization.
  * @param {string} repoName string name of the Github repository.
  * @return {number} number of stars given to a Github repository.
  */
  async function getStarCount(userName, repoName) {
    try {
      //You can change this URL to any web request you want to work with.
      const url = "https://api.github.com/repos/" + userName + "/" + repoName;
      const response = await fetch(url);
      //Expect that status code is in 200-299 range
      if (!response.ok) {
        throw new Error(response.statusText)
      }
        const jsonResponse = await response.json();
        return jsonResponse.watchers_count;
    }
    catch (error) {
      return error;
    }
  }
  1. 次のコマンドを実行してプロジェクトを再構築します。Run the following command to rebuild the project.

    npm run build
    
  2. Excel でアドインを再登録するには、次の手順を実行します (web、Windows、または Mac の Excel の場合)。Complete the following steps (for Excel on the web, Windows, or Mac) to re-register the add-in in Excel. 新しい関数を使用できるようにするには、これらの手順を完了する必要があります。You must complete these steps before the new function will be available.

  1. Excel を閉じて再び開きます。Close Excel and then reopen Excel.

  2. Excel で [挿入] タブを選択し、[マイアドイン] の右側にある下向き矢印を選択します。 [個人用アドイン] 矢印が強調表示されている Windows 上の Excel でのリボンの挿入In Excel, choose the Insert tab and then choose the down-arrow located to the right of My Add-ins. Insert ribbon in Excel on Windows with the My Add-ins arrow highlighted

  3. 利用可能なアドインの一覧で、[開発者用アドイン] セクションを見つけ、 starcountアドインを選択して登録します。In the list of available add-ins, find the Developer Add-ins section and select the starcount add-in to register it. [個人用アドイン] ボックスの一覧で強調表示された Excel カスタム関数アドインを使用して、Excel の Excel にリボンを挿入するInsert ribbon in Excel on Windows with the Excel Custom Functions add-in highlighted in the My Add-ins list

  1. 新しい関数をお試しください。Try out the new function. セルB1に、「CONTOSO」というテキストを入力します。GETSTARCOUNT ("OfficeDev", "Excel-ユーザー定義関数") 。 enter キーを押します。In cell B1, type the text =CONTOSO.GETSTARCOUNT("OfficeDev", "Excel-Custom-Functions") and press enter. セルB1の結果は、 [Excel のカスタム機能である Github リポジトリ](https://github.com/OfficeDev/Excel-Custom-Functions)に与えられている現在の星数であることがわかります。You should see that the result in cell B1 is the current number of stars given to the [Excel-Custom-Functions Github repository](https://github.com/OfficeDev/Excel-Custom-Functions).

非同期でデータをストリーミングするカスタム関数を作成するCreate a streaming asynchronous custom function

関数getStarCountは、特定の時点でリポジトリにある星の数を返します。The getStarCount function returns the number of stars a repository has at a specific moment in time. カスタム関数は、絶えず変化するデータを返すこともできます。Custom functions can also return data that is continuously changing. これらの関数は、ストリーミング関数と呼ばれます。These functions are called streaming functions. これらには、 invocation関数が呼び出されたセルを参照するパラメーターを含める必要があります。They must include an invocation parameter which refers to the cell where the function was called from. invocationパラメーターは、セルの内容をいつでも更新するために使用されます。The invocation parameter is used to update the contents of the cell at any time.

次のコードサンプルでは、 currentTimeclockの2つの関数があることに注意してください。In the following code sample, you'll notice that there are two functions, currentTime and clock. 関数currentTimeは、ストリーミングを使用しない静的関数です。The currentTime function is a static function that does not use streaming. 日付を文字列として返します。It returns the date as a string. clock関数は、 currentTime関数を使用して、Excel のセルに対して2秒ごとに新しい時刻を提供します。The clock function uses the currentTime function to provide the new time every second to a cell in Excel. を使用invocation.setResultして、Excel セルに時刻を提供invocation.onCanceledし、関数がキャンセルされたときに発生する処理を処理します。It uses invocation.setResult to deliver the time to the Excel cell and invocation.onCanceled to handle what occurs when the function is canceled.

  1. Starcountプロジェクトで、次のコードを /src/functions/functions.jsに追加し、ファイルを保存します。In the starcount project, add the following code to ./src/functions/functions.js and save the file.
/**
 * Returns the current time
 * @returns {string} String with the current time formatted for the current locale.
 */
function currentTime() {
  return new Date().toLocaleTimeString();
}

 /**
 * Displays the current time once a second
 * @customfunction
 * @param {CustomFunctions.StreamingInvocation<string>} invocation Custom function invocation
 */
function clock(invocation) {
  const timer = setInterval(() => {
    const time = currentTime();
    invocation.setResult(time);
  }, 1000);

  invocation.onCanceled = () => {
    clearInterval(timer);
  };
}
  1. 次のコマンドを実行してプロジェクトを再構築します。Run the following command to rebuild the project.

    npm run build
    
  2. Excel でアドインを再登録するには、次の手順を実行します (web、Windows、または Mac の Excel の場合)。Complete the following steps (for Excel on the web, Windows, or Mac) to re-register the add-in in Excel. 新しい関数を使用できるようにするには、これらの手順を完了する必要があります。You must complete these steps before the new function will be available.

  1. Excel を閉じて再び開きます。Close Excel and then reopen Excel.

  2. Excel で [挿入] タブを選択し、[マイアドイン] の右側にある下向き矢印を選択します。 [個人用アドイン] 矢印が強調表示されている Windows 上の Excel でのリボンの挿入In Excel, choose the Insert tab and then choose the down-arrow located to the right of My Add-ins. Insert ribbon in Excel on Windows with the My Add-ins arrow highlighted

  3. 利用可能なアドインの一覧で、[開発者用アドイン] セクションを見つけ、 starcountアドインを選択して登録します。In the list of available add-ins, find the Developer Add-ins section and select the starcount add-in to register it. [個人用アドイン] ボックスの一覧で強調表示された Excel カスタム関数アドインを使用して、Excel の Excel にリボンを挿入するInsert ribbon in Excel on Windows with the Excel Custom Functions add-in highlighted in the My Add-ins list

  1. 新しい関数をお試しください。Try out the new function. セルC1に、「CONTOSO」というテキストを入力します。CLOCK ())と入力し、enter キーを押します。In cell C1, type the text =CONTOSO.CLOCK()) and press enter. 現在の日付が表示され、1秒ごとに更新が流れます。You should see the current date, which streams an update every second. このクロックはループのタイマーにすぎませんが、リアルタイムデータに対する web 要求を行う、より複雑な関数でタイマーを設定するのと同じ概念を使用できます。While this clock is just a timer on a loop, you can use the same idea of setting a timer on more complex functions that make web requests for real-time data.

次のステップNext steps

おめでとうございます。Congratulations! 新しいカスタム関数プロジェクトを作成し、あらかじめ作成された関数を試し、web からデータを要求するカスタム関数を作成し、データをストリーム処理するカスタム関数を作成しました。You've created a new custom functions project, tried out a prebuilt function, created a custom function that requests data from the web, and created a custom function that streams data. この関数のデバッグは、カスタム関数のデバッグ手順を使用して実行することもできます。You can also try out debugging this function using the custom function debugging instructions. Excel のカスタム関数に関する詳細については、次の記事にお進みください。To learn more about custom functions in Excel, continue to the following article: