Excel でカスタム関数を作成するCreate custom functions in Excel

開発者は、カスタム関数を使用して関数をアドインの一部として 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.

重要

Excel カスタム関数は、次のプラットフォームで使用できることに注意してください。Note that Excel custom functions are available on the following platforms.

  • Office on Windows (Office 365 サブスクリプションに接続されたバージョン1904以降)Office on Windows (version 1904 or later, connected to Office 365 subscription)
  • Office on Mac (Office 365 サブスクリプションに接続されたバージョン16.24 以降)Office on Mac (version 16.24 or later, connected to Office 365 subscription)
  • Web 上の OfficeOffice on the web

Excel カスタム関数は、現在 iPad または Office 2019 以前の1回限りの購入バージョンではサポートされていません。Excel custom functions are currently not supported on iPad or in one-time purchase versions of Office 2019 or earlier.

次のアニメーション画像は、JavaScript または Typescript で作成した関数を呼び出すブックを示しています。The following animated image shows your workbook calling a function you've created with JavaScript or Typescript. この例では、カスタム関数 =MYFUNCTION.SPHEREVOLUME は球の体積を計算します。In this example, the custom function =MYFUNCTION.SPHEREVOLUME calculates the volume of a sphere.

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

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

/**
 * Returns the volume of a sphere. 
 * @customfunction
 * @param {number} radius
 */
function sphereVolume(radius) {
  return Math.pow(radius, 3) * 4 * Math.PI / 3;
}
CustomFunctions.associate("SPHEREVOLUME", sphereVolume)

注意

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

コードでカスタム関数を定義する方法How a custom function is defined in code

Yo Office ジェネレーターを使用して Excel のカスタム関数アドイン プロジェクトを作成する場合、使用する関数、作業ウィンドウ、およびアドイン全体をこのジェネレーターが作成します。If you use the Yo Office generator to create an Excel custom functions add-in project, you'll find that it creates files which control your functions, your task pane, and your add-in overall. このため、カスタム関数に重要なファイルに注意を集中できます。We'll concentrate on the files that are important to custom functions:

ファイルFile ファイル形式File format 説明Description
./src/functions/functions.js./src/functions/functions.js
またはor
./src/functions/functions.ts./src/functions/functions.ts
JavaScriptJavaScript
またはor
TypeScriptTypeScript
カスタム関数を定義するコードが含みます。Contains the code that defines custom functions.
./src/functions/functions.html./src/functions/functions.html HTMLHTML カスタム関数を定義する JavaScript ファイルに <script> 参照を提供します。Provides a <script> reference to the JavaScript file that defines custom functions.
./manifest.xml./manifest.xml XMLXML アドイン内のすべてのカスタム関数の名前空間と、この表で前述した JavaScript ファイルと HTML ファイルの位置を指定します。Specifies the namespace for all custom functions within the add-in and the location of the JavaScript and HTML files that are listed previously in this table. また、作業ウィンドウ ファイルやコマンド ファイルなど、アドインで使用する可能性のある他のファイルの位置もリストされます。It also lists the locations of other files your add-in might make use of, such as the task pane files and command files.

スクリプト ファイルScript file

スクリプト ファイル (./src/customfunctions.js または /src/customfunctions.ts) は、カスタム関数を定義し、どのコードがその関数を定義するかをコメントし、カスタム関数の名前を JSON メタデータ ファイルのオブジェクトに関連付けるコードを格納しています。The script file (./src/functions/functions.js or ./src/functions/functions.ts) contains the code that defines custom functions, comments which define the function, and associates the names of the custom functions to objects in the JSON metadata file.

add カスタム関数は次のコードにより定義されます。The following code defines the custom function add. コード コメントは、Excel にカスタム関数を記述する JSON メタデータ ファイルを生成するために使用されます。The code comments are used to generate a JSON metadata file that describes the custom function to Excel. 必須の @customfunction コメントが最初に宣言されて、これがカスタム関数であることを示します。The required @customfunction comment is declared first, to indicate that this is a custom function. さらに、お気付きのように firstsecond の 2 つのパラメーターが宣言されており、その後にそれらの description プロパティが記述されます。Additionally, you'll notice two parameters are declared, first and second, which are followed by their description properties. 最後に returns の説明が記述されます。Finally, a returns description is given. カスタム関数で必要になるコメントに関する詳細については、「カスタム関数の JSON メタデータを作成する」を参照してください。For more information about what comments are required for your custom function, see Create JSON metadata for custom functions.

次のコードでは、CustomFunctions.associate("ADD", add) も呼び出して、add() 関数を JSON メタデータ ファイル ADD の ID と関連付けます。The following code also calls CustomFunctions.associate("ADD", add) to associate the function add() with its ID in the JSON metadata file ADD. 関数の関連付けに関する詳細については、「カスタム関数のベスト プラクティス」を参照してください。For more information about associating functions, see Custom functions best practices.

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number.
 * @param second Second number.
 * @returns The sum of the two numbers.
 */

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

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

カスタム関数のランタイムの読み込みを制御する functions.html ファイルは、カスタム関数の現在の CDN にリンクしていなければならないことに注意してください。Note that the functions.html file, which governs the loading of the custom functions runtime, must link to the current CDN for custom functions. 最新バージョンの Yo Office ジェネレーターを使用して作成されたプロジェクトは、正しい CDN を参照します。Projects prepared with the current version of the Yo Office generator reference the correct CDN. 2019 年 3 月以前の古いカスタム関数のプロジェクトを改良する場合は、以下のコードを functions.html ページにコピーする必要があります。If you are retrofitting a previous custom function project from March 2019 or earlier, you need to copy in the code below to the functions.html page.

<script src="https://appsforoffice.microsoft.com/lib/beta/hosted/custom-functions-runtime.js" type="text/javascript"></script>

マニフェスト ファイル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 basic 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. Yo Office ジェネレーターを使用する場合、生成されたカスタム関数ファイルには、さらに複雑なマニフェスト ファイルが格納されます。こちらのGithub リポジトリで比較できます。If using the Yo Office generator, your generated custom function files will contain a more complex manifest file, which you can compare on this Github repository.

注意

カスタム関数のJavaScript、JSON、HTML ファイルのマニフェスト ファイルで指定した URL はだれでもアクセスでき、同じサブドメインを持つ必要があります。The URLs specified in the manifest file for the custom functions JavaScript, JSON, and HTML files must be publicly accessible and have the same subdomain.

<?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://subdomain.contoso.com/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://subdomain.contoso.com/dist/win32/ship/index.win32.bundle"/>
        <bt:Url id="HTML-URL" DefaultValue="https://subdomain.contoso.com/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.

共同編集Coauthoring

Excel on the web と Office 365 サブスクリプションに接続している Windows の場合は、ドキュメントの共同編集を行うことができます。また、この機能でカスタム関数を使用できます。Excel Online and Excel on Windows with an Office 365 subscription allow you to coauthor documents and this feature works with custom functions. ブックでカスタム関数を使用している場合、仕事仲間はカスタム関数のアドインを読み込むように要求されます。If your workbook uses a custom function, your colleague will be prompted to load the custom function's add-in. 双方がアドインを読み込むと、共同編集によりカスタム関数は結果を共有します。Once you both have loaded the add-in, the custom function will share results through coauthoring.

共同編集の詳細については、「Excel での共同編集」を参照してください。For more information on coauthoring, see About coauthoring in Excel.

既知の問題Known issues

既知の問題については、Excel カスタム関数についての GitHub のレポートを参照してください。See known issues on our Excel Custom Functions GitHub repo.

次の手順Next steps

カスタム関数を試してみましょう。Want to try out custom functions? もしまだであれば、簡単なカスタム関数クイックスタートまたは、詳細なカスタム関数のチュートリアルをご覧ください。Check out the simple custom functions quick start or the more in-depth custom functions tutorial if you haven't already.

独自のカスタム関数を試すもう 1 つの簡単な方法はスクリプト ラボを使用し、アドインで Excel のカスタム関数を試してみることができます。Another easy way to try out custom functions is to use Script Lab, an add-in that allows you to experiment with custom functions right in Excel. 独自のカスタム関数を作成したり、提供されたサンプルを再生してみることができます。You can try out creating your own custom function or play with the provided samples.

カスタム関数の機能の詳細について読む準備はできましたか?Ready to read more about the capabilities custom functions? カスタム関数のアーキテクチャの概要をご覧ください。Learn about an overview of the custom functions architecture.

関連項目See also