カスタム関数の JSON メタデータを手動で作成する

カスタム関数の概要に関する記事で説明されているように、カスタム関数プロジェクトには、JSON メタデータファイルとスクリプト (JavaScript または TypeScript) ファイルの両方を含めて関数を登録し、使用できるようにする必要があります。カスタム関数は、ユーザーが初めてアドインを実行したときに登録され、その後、すべてのブックで同じユーザーが使用できるようになります。

重要

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

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

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

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

注:

Microsoft 365 の統合マニフェストでは、現在、カスタム関数プロジェクトはサポートされていません。カスタム関数プロジェクトにはアドインのみのマニフェストを使用する必要があります。詳細については、「 Office アドインマニフェスト」を参照してください。

独自の JSON ファイルを作成する代わりに、可能な場合は JSON 自動生成を使用することをお勧めします。自動生成はユーザーエラーが発生しにくく、 yo office スキャフォールディングされたファイルには既にこれが含まれています。 JSDoc タグと JSON 自動生成プロセスの詳細については、「カスタム関数の JSON メタデータの自動生成」を参照してください。

ただし、カスタム関数プロジェクトはゼロから作成できます。このプロセスでは、次の作業を行う必要があります。

JSON ファイルを書き込みます。
マニフェストファイルが JSON ファイルに接続されていることを確認します。
関数を登録するために、スクリプトファイルに関数の id と name プロパティを関連付けます。

次の図は、スキャフォールディングファイルの使用と JSON のゼロからの書き込みの違い yo office 説明しています。

Office アドインに Yeoman ジェネレーターを使用することと、独自の JSON を記述することの違いの画像。

注:

Office アドイン用の Yeoman ジェネレーターを使用しない場合は、アドインのみのマニフェストファイルの <Resources> セクションを使用して、作成した JSON ファイルにマニフェストを接続してください。

メタデータの作成とマニフェストへの接続

プロジェクトに JSON ファイルを作成し、関数のパラメーターなど、その中の関数に関するすべての詳細を指定します。関数プロパティの完全な一覧については、次のメタデータの例とメタデータリファレンスを参照してください。

アドインのみのマニフェストファイルが、次の例のように、 <Resources> セクションの JSON ファイルを参照していることを確認します。

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

JSON メタデータの例

次の例では、カスタム関数を定義するアドインの JSON メタデータファイルの内容を示します。この例の後に続くセクションでは、JSON の例に含まれる個々のプロパティの詳細について説明します。

{
  "allowCustomDataForDataTypeAny": true,
  "allowErrorForDataTypeAny": true,
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      "description": "Add two numbers",
      "helpUrl": "http://www.contoso.com/help",
      "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": "GETDAY",
      "name": "GETDAY",
      "description": "Get the day of the week",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": []
    },
    {
      "id": "INCREMENTVALUE",
      "name": "INCREMENTVALUE",
      "description": "Count up from zero",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "increment",
          "description": "the number to be added each time",
          "type": "number",
          "dimensionality": "scalar"
        }
      ],
      "options": {
        "stream": true,
        "cancelable": true
      }
    },
    {
      "id": "GETPLANETS", 
      "name": "GETPLANETS", 
      "description": "A function that uses the custom enum as a parameter.", 
      "parameters": [ 
        { 
          "name": "value", 
          "type": "string", 
          "customEnumType": "PLANETS" 
        }
      ]
    }
  ],
  "enums": [ 
    { 
      "id": "PLANETS", 
      "type": "string", 
      "values": [ 
        { 
          "name": "Mercury", 
          "value": "mercury", 
          "tooltip": "Mercury is the first planet from the sun." 
        }, 
        { 
          "name": "Venus", 
          "value": "venus", 
          "tooltip": "Venus is the second planet from the sun." 
        }
      ] 
    }
  ]
}

注:

完全なサンプル JSON ファイルは、 OfficeDev/Excel-Custom-Functions GitHub リポジトリのコミット履歴で入手できます。プロジェクトが JSON を自動的に生成するように調整されているため、手書き JSON の完全なサンプルは、以前のバージョンのプロジェクトでのみ使用できます。

メタデータリファレンス

allowCustomDataForDataTypeAny

allowCustomDataForDataTypeAny プロパティはブール型です。この値を true に設定すると、カスタム関数はデータ型をパラメーターとして受け入れ、値を返すことができます。詳細については、「カスタム関数とデータ型」を参照してください。

注:

他のほとんどの JSON メタデータプロパティとは異なり、 allowCustomDataForDataTypeAny は最上位のプロパティであり、サブプロパティが含まれています。このプロパティの書式を設定する方法の例については、前の JSON メタデータコードサンプルを参照してください。

カスタム関数で cellValueTypeパラメーターを使用する場合、データ型をパラメーターとして受け入れて値を返すためにallowCustomDataForDataTypeAnyを設定する必要はありません。

allowErrorForDataTypeAny

allowErrorForDataTypeAny プロパティはブール型です。値を true に設定すると、カスタム関数でエラーを入力値として処理できます。型 any または any[][] を持つすべてのパラメーターは、 allowErrorForDataTypeAny が true に設定されている場合、入力値としてエラーを受け取ることができます。既定の allowErrorForDataTypeAny 値は falseです。

注:

他の JSON メタデータプロパティとは異なり、 allowErrorForDataTypeAny は最上位のプロパティであり、サブプロパティが含まれています。このプロパティの書式を設定する方法の例については、前の JSON メタデータコードサンプルを参照してください。

functions

functions プロパティは、カスタム関数オブジェクトの配列です。次の表に、各オブジェクトのプロパティを示します。

プロパティ	データ型	必須	説明
`description`	文字列	いいえ	Excel でエンドユーザーに表示される関数の説明です。たとえば、「華氏の値を摂氏に変換する」です。
`helpUrl`	文字列	いいえ	関数に関する情報を提供する URL ですたとえば、「 `http://contoso.com/help/convertcelsiustofahrenheit.html` 」のように入力します。
`id`	string	はい	関数の一意の ID です。この ID には、英数字とピリオドしか使用できません。また、設定後に変更してはいけません。
`name`	文字列	はい	Excel でエンドユーザーに表示される関数の名前です。 Excel では、この関数名の前に、アドインのみのマニフェストファイルで指定されているカスタム関数名前空間が付きます。
`options`	object	いいえ	Excel で関数を実行する方法とタイミングの一部をユーザーがカスタマイズできます。詳細については、options に関する説明を参照してください。
`parameters`	配列	はい	関数の入力パラメーターを定義する配列です。詳細については、「パラメーター」を参照してください。
`result`	object	はい	関数が返す情報の種類を定義するオブジェクトです。詳細については、result に関する説明を参照してください。

enums

enums プロパティは、列挙型オブジェクトの配列です。次の表に、各オブジェクトのプロパティを示します。

ヒント

カスタム関数のカスタム列挙型の作成については、「カスタム関数のカスタム列挙型を作成する」を参照してください。カスタム列挙型のメタデータの編集については、「 JSON メタデータでカスタム列挙型を編集する」を参照してください。

プロパティ	データ型	必須	説明
`name`	string	はい	定数の簡単な説明。
`tooltip`	文字列	いいえ	ユーザーインターフェイスのヒントとして表示できる定数に関する追加情報。
`value`	string	はい	定数の値。

options

options オブジェクトでは、Excel で関数を実行する方法とタイミングの一部をユーザーがカスタマイズできます。次の表に、options オブジェクトのプロパティを示します。

プロパティ	データ型	必須	説明
`cancelable`	ブール型	いいえ既定値は、`false` です。	`true` の場合、手動での再計算のトリガーや、関数によって参照されているセルの編集など、関数をキャンセルする効果のある操作をユーザーが実行すると、Excel によって `CancelableInvocation` ハンドラーが呼び出されます。取り消し可能な関数は通常、1 つの結果を返す非同期関数にのみ使用され、データに対する要求の取り消しを処理する必要があります。関数では、 `stream` プロパティと `cancelable` プロパティの両方を使用することはできません。
`capturesCallingObject`	ブール型	いいえ既定値は、`false` です。	`true`場合、カスタム関数によって参照されているデータ型が、カスタム関数の最初の引数として渡されます。詳細については、「呼び出し元オブジェクトとしてエンティティ値を参照する」を参照してください。
`excludeFromAutoComplete`	ブール型	いいえ既定値は、`false` です。	`true`場合、Excel の数式オートコンプリートメニューにカスタム関数は表示されません。詳細については、「 Excel UI からカスタム関数を除外する」を参照してください。関数では、 `excludeFromAutoComplete` プロパティと `linkedEntityLoadService` プロパティの両方を `true` に設定することはできません。
`linkedEntityLoadService`	ブール型	いいえ既定値は、`false` です。	`true`場合、カスタム関数は、Excel によって要求されたすべてのリンクされたエンティティ ID の最新のリンクされたエンティティセル値を返すロードサービスを提供します。関数では、 `excludeFromAutoComplete` プロパティと `linkedEntityLoadService` プロパティの両方を `true` に設定することはできません。詳細については、「リンクされたエンティティ読み込みサービス関数」を参照してください。
`requiresAddress`	ブール型	いいえ既定値は、`false` です。	`true`場合、カスタム関数は、それを呼び出したセルのアドレスにアクセスできます。呼び出しパラメーターの `address` プロパティには、カスタム関数を呼び出したセルのアドレスが含まれています。関数では、 `stream` プロパティと `requiresAddress` プロパティの両方を使用することはできません。
`requiresParameterAddresses`	ブール型	いいえ既定値は、`false` です。	`true`場合、カスタム関数は関数の入力パラメーターのアドレスにアクセスできます。このプロパティは、結果オブジェクトの `dimensionality` プロパティと組み合わせて使用し、`dimensionality`を `matrix` に設定する必要があります。詳細については、「パラメーターのアドレスを検出する」を参照してください。
`requiresStreamAddress`	ブール型	いいえ既定値は、`false` です。	`true`場合、関数はストリーミング関数を呼び出すセルのアドレスにアクセスできます。呼び出しパラメーターの `address` プロパティには、ストリーミング関数を呼び出したセルのアドレスが含まれています。関数には、`true`に設定`stream`も必要です。
`requiresStreamParameterAddresses`	ブール型	いいえ既定値は、`false` です。	`true`場合、関数はストリーミング関数を呼び出すセルのパラメーターアドレスにアクセスできます。呼び出しパラメーターの `parameterAddresses` プロパティには、ストリーミング関数のパラメーターアドレスが含まれています。関数には、`true`に設定`stream`も必要です。
`stream`	ブール型	いいえ既定値は、`false` です。	`true` の場合、1 回のみ呼び出されたときにも、関数はセルに繰り返し出力できます。このオプションは、株価などの急速に変化するデータソースに便利です。この関数には、`return` ステートメントは含めないようにする必要があります。代わりに、結果の値は、 `StreamingInvocation.setResult` コールバック関数の引数として渡されます。詳細については、「ストリーミング関数を作成する」を参照してください。
`volatile`	ブール型	いいえ既定値は、`false` です。	`true`場合、関数は、数式の依存値が変更された場合にのみではなく、Excel が再計算されるたびに再計算されます。関数では、 `stream` プロパティと `volatile` プロパティの両方を使用することはできません。 `stream`プロパティと`volatile`プロパティの両方が`true`に設定されている場合、volatile プロパティは無視されます。

parameters

parameters プロパティは、パラメーターオブジェクトの配列です。次の表に、各オブジェクトのプロパティを示します。

プロパティ	データ型	必須	説明
`description`	文字列	いいえ	パラメーターの説明です。これは Excel の IntelliSense に表示されます。
`dimensionality`	文字列	いいえ	`scalar` (配列以外の値) または`matrix` (2 次元配列) である必要があります。
`name`	string	はい	パラメーターの名前です。この名前は、Excel の IntelliSense に表示されます。
`type`	文字列	いいえ	パラメーターのデータ型です。 `boolean`、`number`、`string`、または`any`を使用できます。これにより、前の 3 種類のいずれかを使用できます。このプロパティが指定されていない場合、データ型は既定で `any`されます。
`cellValueType`	文字列	いいえ	`type` プロパティのサブフィールド。カスタム関数で受け入れられる Excel データ型を指定します。大文字と小文字を区別しない値 `cellvalue`、 `booleancellvalue`、 `doublecellvalue`、 `entitycellvalue`、 `errorcellvalue`、 `linkedentitycellvalue`、 `localimagecellvalue`、 `stringcellvalue`、 `webimagecellvalue`を受け入れます。 `cellValueType` サブフィールドを使用するには、`type` フィールドに`any`値が必要です。
`customEnumType`	文字列	いいえ	`enums`配列内の列挙型の`id`。これにより、カスタム列挙型が関数に関連付けられます。これにより、Excel は数式 AutoComplete メニューに列挙型メンバーを表示できます。
`optional`	ブール型	いいえ	`true` の場合、パラメーターは省略可能です。
`repeating`	ブール型	いいえ	`true`場合、パラメーターは指定した配列から設定されます。すべての繰り返しパラメーターは、定義上省略可能なパラメーターと見なされることに注意してください。

ヒント

JSON メタデータで cellValueType パラメーターを書式設定する方法の例については、次のコードスニペットを参照してください。

"parameters": [
    {
        "name": "range",
        "description": "the input range",
        "type": "any",
            "cellValueType": "webimagecellvalue"
    }
]

result

result オブジェクトは、この関数が返す情報の種類を定義します。次の表に、result オブジェクトのプロパティを示します。

プロパティ	データ型	必須	説明
`dimensionality`	文字列	いいえ	`scalar` (配列以外の値) または`matrix` (2 次元配列) である必要があります。
`type`	文字列	いいえ	結果のデータ型。 `boolean`、`number`、`string`、または`any`を指定できます (これは、前の 3 種類のいずれかを使用できます)。このプロパティが指定されていない場合、データ型は既定で `any`されます。

関数名を JSON メタデータに関連付ける

関数が正常に機能するには、関数の id プロパティを JavaScript 実装に関連付ける必要があります。関連付けがあることを確認します。それ以外の場合、関数は登録されないため、Excel では使用できません。次のコードサンプルは、 CustomFunctions.associate() 関数を使用して関連付けを行う方法を示しています。このサンプルではカスタム関数 add を定義し、それを id プロパティ値が ADD の、JSON メタデータファイル内のオブジェクトに関連付けます。

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

CustomFunctions.associate("ADD", add);

次の JSON は、前のカスタム関数 JavaScript コードに関連付けられている JSON メタデータを示しています。

{
  "functions": [
    {
      "description": "Add two numbers",
      "id": "ADD",
      "name": "ADD",
      "parameters": [
        {
          "description": "First number",
          "name": "first",
          "type": "number"
        },
        {
          "description": "Second number",
          "name": "second",
          "type": "number"
        }
      ],
      "result": {
        "type": "number"
      }
    }
  ]
}

JavaScript ファイルでカスタム関数を作成し、JSON のメタデータファイルに対応する情報を指定するときは、次のベストプラクティスに留意してください。

JSON のメタデータファイルにそれぞれの id プロパティには、英数字とピリオドのみが含まれています。
JSON のメタデータファイルで、各 id プロパティの値が、ファイルのスコープ内で一意であることを確認します。すなわち、メタデータファイル内の 2 つの関数オブジェクトは同じ id 値であってはいけません。
対応する JavaScript 関数の名前に関連付けられた後では、JSON のメタデータファイル内の id プロパティの値を変更しないでください。 JSON のメタデータファイル内の name プロパティを更新することによって Excel でエンドユーザーに表示される関数の名前を変更することができます。しかし、確立された後は、 id プロパティの値を決して変更しないでください。
JavaScript ファイルで、各関数の後に CustomFunctions.associate を使用してカスタム関数の関連付けを指定します。

次の例は、前の JavaScript コードサンプルで定義されている関数に対応する JSON メタデータを示しています。 idプロパティとnameプロパティの値は大文字です。これは、カスタム関数を記述する際のベストプラクティスです。この JSON を追加する必要があるのは、自動生成を使用せず、独自の JSON ファイルを手動で準備している場合のみです。自動生成の詳細については、「カスタム関数の JSON メタデータの自動生成」を参照してください。

{
  "$schema": "https://developer.microsoft.com/json-schemas/office-js/custom-functions.schema.json",
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      ...
    },
    {
      "id": "INCREMENT",
      "name": "INCREMENT",
      ...
    }
  ]
}

JSON メタデータでカスタム列挙型を編集する

enums プロパティを使用して列挙メタデータを直接作成または編集します。各カスタム列挙型には、 string または numberのいずれかの一意の ID 値と型値が必要です。混合型列挙型はサポートされていません。

カスタム列挙型の JSON メタデータを手動で作成する場合は、それらの列挙型を TypeScript または JavaScript カスタム関数のいずれかに関連付けることができます。カスタム列挙型の作成の詳細については、「カスタム関数のカスタム列挙型を作成する」を参照してください。

次の JSON スニペットは、2 つの列挙型のメタデータを示しています。惑星水星と金星を含む PLANETS 列挙型と、月曜日と火曜日の日数を含む DAYS 列挙型。

"enums": [ 
  { 
    "id": "PLANETS", 
    "type": "string", 
    "values": [ 
      { 
        "name": "Mercury", 
        "value": "mercury", 
        "tooltip": "Mercury is the first planet from the sun." 
      }, 
      { 
        "name": "Venus", 
        "value": "venus", 
        "tooltip": "Venus is the second planet from the sun." 
      }
    ] 
  },
  {
    "id": "DAYS", 
    "type": "number", 
    "values": [ 
      { 
        "name": "Monday",
        "value": 1,
        "tooltip": "Monday is the first working day of a week."
      },
      { 
        "name": "Tuesday",
        "value": 2,
        "tooltip": "Tuesday is the second working day of a week."
      }
    ] 
  }
]

列挙型の values 配列内の各定数は、次のプロパティを持つオブジェクトです。

value: 定数の値。
name: 定数の簡単な説明。
tooltip (省略可能): ユーザーインターフェイスのヒントとして表示できる定数に関する追加情報。

カスタム列挙型を関数に関連付けるには、parameters オブジェクトにcustomEnumTypeプロパティを追加します。 customEnumType値は列挙型のidと一致する必要があります。 customEnumType値では大文字と小文字は区別されないことに注意してください。次の JSON スニペットは、PLANETS列挙型に関連付けられているfunctions オブジェクトを示しています。

"functions": [ 
  {
    "description": "A function that uses the custom enum as a parameter.", 
    "id": "GETPLANETS", 
    "name": "GETPLANETS", 
    "parameters": [ 
      { 
        "name": "value", 
        "type": "string", 
        "customEnumType": "PLANETS" 
      }
    ], 
    "result": {} 
  } 
]

次の手順

関数の名前付けのベストプラクティスについて説明するか、前に説明した手書き JSON メソッドを使用して関数をローカライズする方法を確認します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-27