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

• 06/20/2019
• • 
  • 

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

次のアニメーション画像は、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.

=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)

コードでカスタム関数を定義する方法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:

スクリプト ファイル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. さらに、お気付きのように first と second の 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.

<?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>

共同編集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

• カスタム関数の要件Custom functions requirements
• 名前付けのガイドラインNaming guidelines
• ベスト プラクティスBest practices
• XLL ユーザー定義関数と互換性のある、カスタム関数を作成します。Make your custom functions compatible with XLL user-defined functions