カスタム関数用の JSON メタデータの自動生成

[アーティクル]
07/29/2023

Excel カスタム関数が JavaScript または TypeScript で記述されている場合、カスタム関数に関する追加の情報を提供するために、JSDoc タグが使用されます。これらの JSDoc タグを使用して、ビルド時に JSON メタデータファイルを自動的に作成する Webpack プラグインを提供します。プラグインを使用すると、 JSON メタデータファイルを手動で編集する手間が省けます。

重要

Excel カスタム関数は、次のプラットフォームで使用できます。

Office on the web
Windows での Office
- Microsoft 365 サブスクリプション
- retail 永久 Office 2016 以降
- ボリュームライセンスの永続的な Office 2021 以降
Office on Mac

Excel カスタム関数は現在、次ではサポートされていません。

Office on iPad
Windows での Office 2019 以前のボリュームライセンスの永続的バージョン

CustomFunctionsMetadataPlugin

プラグインは CustomFunctionsMetadataPlugin です。インストールして構成するには、次の手順を使用します。

注:

このツールは、NodeJS ベースのプロジェクトでのみ使用できます。
これらの手順では、プロジェクトで Webpack が使用されていること、およびインストールおよび構成済みであることを前提としています。
Office アドイン用 Yeoman ジェネレーターを使用してカスタム関数アドインプロジェクトを作成した場合、Webpack がインストールされ、これらの手順はすべて自動的に実行されますが、該当する場合は、「複数のカスタム関数ソースファイル」の手順を手動で実行する必要があります。

コマンドプロンプトまたは bash シェルを開き、プロジェクトのルートで npm install custom-functions-metadata-pluginを実行します。
webpack.config.js ファイルを開き、上部に次の行を追加します: const CustomFunctionsMetadataPlugin = require("custom-functions-metadata-plugin");。
plugins配列まで下にスクロールし、配列の先頭に次を追加します。必要に応じて input パスとファイル名をプロジェクトに合わせて変更しますが、 output 値は "functions.json" である必要があります。 TypeScript を使用している場合は、変換された *.js ファイル ではなく 、*.ts ソースファイル名を使用します。
```
new CustomFunctionsMetadataPlugin({
   output: "functions.json",
   input: "./src/functions/functions.js", 
}),
```

複数のカスタム関数ソースファイル

カスタム関数を複数のソースファイルに整理した場合にのみ、追加の手順があります。

webpack.config.js ファイルで、 input の文字列値を、各ファイルを指す文字列 URL の配列に置き換えます。例を次に示します。

new CustomFunctionsMetadataPlugin({
   output: "functions.json",
   input: [
            "./src/functions/someFunctions.js", 
            "./src/functions/otherFunctions.js"
          ], 
}),

entry.functions プロパティまでスクロールし、その値を前の手順で使用したのと同じ配列に置き換えます。例を次に示します。

entry: {
   polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
   taskpane: ["./src/taskpane/taskpane.js", "./src/taskpane/taskpane.html"],
   functions: [
            "./src/functions/someFunctions.js", 
            "./src/functions/otherFunctions.js"
          ],
 },

ツールを実行する

ツールを実行するために何もする必要はありません。 Webpack を実行すると、functions.json ファイルが作成され、開発モードでメモリに格納されるか、運用モードの /dist フォルダーに格納されます。

JSDoc タグの基本

JavaScript または TypeScript 関数のコードコメントに@customfunctionタグを追加して、カスタム関数としてマークします。

関数パラメーターの型は、JavaScript の @param タグを使用して指定するか、TypeScript の関数の型から指定できます。詳細については、「@param タグ」セクションと「型」セクションを参照してください。

関数に説明を追加する

説明は、カスタム関数の機能を理解するためのヘルプが必要な場合に、ヘルプテキストとしてユーザーに表示されます。説明に特定のタグは必要ありません。 JSDoc コメントに簡単な説明を入力するだけです。一般に、説明は JSDoc コメントセクションの先頭に配置されますが、配置場所に関係なく機能します。

組み込み関数の説明の例を表示するには、Excel を開き、[数式] タブに移動し、[関数の挿入] を選択します。すべての関数の説明を参照したり、独自のカスタム関数を一覧表示したりすることができます。

次の例では、"球体のボリュームを計算します" という語句は、カスタム関数の説明です。

/**
/* Calculates the volume of a sphere.
/* @customfunction VOLUME
...
 */

サポートされている JSDoc タグ

Excel カスタム関数では、次の JSDoc タグがサポートされています。

@cancelable
@customfunctionID名
@helpurlURL
@param{type}namedescription
@requiresAddress
@requiresParameterAddresses
@returns{type}
@streaming
@volatile

@cancelable

関数が取り消されたときにカスタム関数がアクションを実行することを示します。

最後の関数パラメーターは CustomFunctions.CancelableInvocation の型にする必要があります。関数は、関数を oncanceled プロパティに割り当てて、関数が取り消されたときに結果を示すことができます。

最後の関数のパラメーターが CustomFunctions.CancelableInvocation 型の場合、タグは表示されませんが、@cancelable と見なされます。

関数には @cancelable と @streaming の両方のタグを含めることはできません。

@customfunction

構文: @customfunctionid名

このタグは、JavaScript/TypeScript 関数が Excel カスタム関数であることを示します。カスタム関数のメタデータを作成する必要があります。

このタグの例を次に示します。

/**
 * Increments a value once a second.
 * @customfunction
 * ...
 */

id

idは、カスタム関数を識別します。

id が提供されていない場合、JavaScript または TypeScript の関数名は大文字に変換され、許可されない文字は削除されます。
id はすべてのカスタム関数で一意である必要があります。
使用できる文字は、A から Z、a-z、0 から 9、アンダースコア (_)、ピリオド (.) に制限されます。

次の例では、インクリメントは関数の id と name です。

/**
 * Increments a value once a second.
 * @customfunction INCREMENT
 * ...
 */

name

カスタム関数の表示用の name を提供します。

name が指定されていない場合、id が名前としても使用されます。
使用できる文字: 文字 Unicode アルファベット、数字、ピリオド (.)、アンダースコア (_)。
最初の文字は、アルファベット文字にする必要があります。
最大文字数は 128 文字です。

次の例では、INC は関数のid で、 increment はnameです。

/**
 * Increments a value once a second.
 * @customfunction INC INCREMENT
 * ...
 */

説明

Excel のユーザーが関数に入力し、関数の動作を指定すると、説明が表示されます。説明に特定のタグは必要ありません。 JSDoc コメント内に関数の機能を説明するフレーズを入力して、カスタム関数に説明を追加します。既定では、JSDoc コメントセクションでタグが付けられていないテキストは、関数の説明です。

次の例では、「2 つの数値を加算する関数」というフレーズが、ID プロパティ ADD のカスタム関数の説明です。

/**
 * A function that adds two numbers.
 * @customfunction ADD
 * ...
 */

@helpurl

構文: @helpurlurl

指定された url が Excel で表示されます。

次の例では、 helpurl が http://www.contoso.com/weatherhelpされています。

/**
 * A function which streams the temperature in a town you specify.
 * @customfunction getTemperature
 * @helpurl http://www.contoso.com/weatherhelp
 * ...
 */

@param

JavaScript

JavaScript 構文: {type} 名の説明@param

{type} は中かっこ内の型情報を指定します。使用できる型に関する詳細については、「型」セクションを参照してください。型が指定されていない場合は、既定の型 any が使用されます。
name は、 @param タグが適用されるパラメーターを指定します。必須です。
description は、Excel で表示される関数のパラメーターの説明を示します。これは省略可能です。

カスタム関数パラメーターを省略可能として示すには、パラメーター名の周りに角かっこを付けます。たとえば、「 @param {string} [text] Optional text 」のように入力します。

注:

省略可能なパラメーターの既定値は null です。

次の例は、2 つまたは 3 つの数値を追加する ADD 関数を示しています。3 番目の数値は省略可能なパラメーターです。

/**
 * A function which sums two, or optionally three, numbers.
 * @customfunction ADDNUMBERS
 * @param firstNumber {number} First number to add.
 * @param secondNumber {number} Second number to add.
 * @param [thirdNumber] {number} Optional third number you wish to add.
 * ...
 */

TypeScript

TypeScript 構文: @paramnameの説明

name は、 @param タグが適用されるパラメーターを指定します。必須です。
description は、Excel で表示される関数のパラメーターの説明を示します。これは省略可能です。

使用できる関数のパラメーターの型に関する詳細については、「型」セクションを参照してください。

カスタム関数のパラメーターを省略可能として示すには、以下のいずれかを実行します。

省略可能なパラメーターを使用する。例: function f(text?: string)
パラメーターに既定値を指定する。例: function f(text: string = "abc")

@paramの詳しい説明については、「JSDoc」を参照してください。

注:

省略可能なパラメーターの既定値は null です。

次の例は、2 つの数値を加算する add 関数を示しています。

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number
 * @param second Second number
 * @returns The sum of the two numbers.
 */
function add(first: number, second: number): number {
  return first + second;
}

@requiresAddress

関数が評価されているセルのアドレスを指定する必要があることを示します。

最後の関数パラメーターは、@requiresAddressを使用するには、CustomFunctions.Invocation型または派生型である必要があります。関数が呼び出されると、address プロパティにアドレスが含まれます。

次の例では、 invocation パラメーターを @requiresAddress と組み合わせて使用して、カスタム関数を呼び出したセルのアドレスを返す方法を示します。詳細については、「呼び出しパラメーター」を参照してください。

/**
 * Return the address of the cell that invoked the custom function. 
 * @customfunction
 * @param {number} first First parameter.
 * @param {number} second Second parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @requiresAddress 
 */
function getAddress(first, second, invocation) {
  const address = invocation.address;
  return address;
}

@requiresParameterAddresses

関数が入力パラメーターのアドレスを返す必要があることを示します。

最後の関数パラメーターは、@requiresParameterAddressesを使用するには、CustomFunctions.Invocation型または派生型である必要があります。 JSDoc コメントには、戻り値がマトリックス (@returns {string[][]}や@returns {number[][]}など) であることを指定する@returnsタグも含める必要があります。詳細については、「マトリックス型」を参照してください。

関数が呼び出されると、 parameterAddresses プロパティには入力パラメーターのアドレスが含まれます。

次の例では、 invocation パラメーターを @requiresParameterAddresses と組み合わせて使用して、3 つの入力パラメーターのアドレスを返す方法を示します。詳細については、「パラメーターのアドレスを検出する」を参照してください。

/**
 * Return the addresses of three parameters. 
 * @customfunction
 * @param {string} firstParameter First parameter.
 * @param {string} secondParameter Second parameter.
 * @param {string} thirdParameter Third parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @returns {string[][]} The addresses of the parameters, as a 2-dimensional array.
 * @requiresParameterAddresses
 */
function getParameterAddresses(firstParameter, secondParameter, thirdParameter, invocation) {
  const addresses = [
    [invocation.parameterAddresses[0]],
    [invocation.parameterAddresses[1]],
    [invocation.parameterAddresses[2]]
  ];
  return addresses;
}

@returns

構文: @returns {type}

戻り値の型を指定します。

{type} を省略すると、TypeScript の型情報が使用されます。型情報がない場合、型は any になります。

次の例は、 @returns タグを使用する add 関数を示しています。

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number
 * @param second Second number
 * @returns The sum of the two numbers.
 */
function add(first: number, second: number): number {
  return first + second;
}

@streaming

カスタム関数がストリーミング関数であることを示すのに使用されます。

最後のパラメーターは CustomFunctions.StreamingInvocation<ResultType> 型です。関数は voidを返します。

ストリーミング関数は値を直接返しません。代わりに、最後のパラメーターを使用して setResult(result: ResultType) を呼び出します。

ストリーム関数によってスローされる例外は無視されます。 setResult() が、エラー結果を示すために、Error により呼び出されることがあります。ストリーミング関数と詳細については、「ストリーミング関数を作成する」を参照してください。

ストリーミング関数は、@volatile としてマークできません。

@volatile

揮発性関数とは、引数を取らない場合や引数が変更されていない場合でも、ある瞬間と次の瞬間では結果が異なる関数です。 Excel では、再計算が実行される度に、揮発性関数を含むセルはすべての参照先と共に、再評価されます。このため、揮発性関数を多用し過ぎると再計算にかかる時間が長くなる可能性があるため、多用しないようにします。

ストリーミング関数に揮発性関数は使用できません。

次の関数は揮発性で、 @volatile タグを使用します。

/**
 * Simulates rolling a 6-sided die.
 * @customfunction
 * @volatile
 */
function roll6sided(): number {
  return Math.floor(Math.random() * 6) + 1;
}

型

パラメーターの型を指定すると、Excel は値を指定した型に変換してから関数を呼び出します。型がanyの場合、変換は実行されません。

値の型

1 つの値は、boolean、 number、stringの型のいずれかを使用して表現できます。

マトリックス型

2 次元配列型を使用して、パラメーターまたは戻り値を値のマトリックスにします。たとえば、 number[][] 型は数値のマトリックスを示し、 string[][] は文字列のマトリックスを示します。

エラーの種類

非ストリーミング関数は、エラーの種類を返すことによりエラーを示すことができます。

ストリーミング関数は、エラーの種類で setResult() を返してエラーを示すことができます。

Promise

カスタム関数は、promise が解決されたときに値を提供する promise を返すことができます。 promise が拒否された場合、カスタム関数はエラーをスローします。

その他の型

その他の型は、エラーとして処理されます。

次の手順

カスタム関数の名前付けとローカライズについて説明します。

次の方法で共有

カスタム関数用の JSON メタデータの自動生成

CustomFunctionsMetadataPlugin

複数のカスタム関数ソースファイル

ツールを実行する

JSDoc タグの基本

関数に説明を追加する

サポートされている JSDoc タグ

@cancelable

@customfunction

id

name

説明

@helpurl

@param

JavaScript

TypeScript

@requiresAddress

@requiresParameterAddresses

@returns

@streaming

@volatile

型

値の型

マトリックス型

エラーの種類

Promise

その他の型

次の手順

関連項目

その他のリソース

次の方法で共有

カスタム関数用の JSON メタデータの自動生成

CustomFunctionsMetadataPlugin

複数のカスタム関数ソース ファイル

ツールを実行する

JSDoc タグの基本

関数に説明を追加する

サポートされている JSDoc タグ

@cancelable

@customfunction

id

name

説明

@helpurl

@param

JavaScript

TypeScript

@requiresAddress

@requiresParameterAddresses

@returns

@streaming

@volatile

型

値の型

マトリックス型

エラーの種類

Promise

その他の型

次の手順

関連項目

その他のリソース

複数のカスタム関数ソースファイル