次の方法で共有

カスタム関数の名前付けとローカライズ

  • [アーティクル]

この記事では、カスタム関数に名前を付ける際のガイドラインとベスト プラクティスについて説明します。 また、カスタム関数名を英語以外の言語にローカライズする方法も示します。

カスタム関数の名前付けのガイドライン

カスタム関数は、JSON メタデータ ファイル内の id プロパティと name プロパティによって識別されます。

  • 関数 id は、JavaScript コード内のカスタム関数を一意に識別するために使用されます。
  • 関数 name は、Excel のユーザーに表示される表示名として使用されます。

重要

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

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

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

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

関数 name は、ローカライズの目的など、関数 idとは異なる場合があります。 一般に、関数の name が異なる理由がない場合は、 id と同じままにする必要があります。

関数の name と id は、いくつかの一般的な要件を共有します。

  • 関数の id では、文字 A から Z、数値 0 から 9、アンダースコア、ピリオドのみを使用できます。

  • 関数の name では、Unicode アルファベット、アンダースコア、ピリオドを使用できます。

  • 関数 name と id の両方が文字で始まり、3 文字の最小制限を持っている必要があります。

Excel では、組み込みの関数名 ( SUM など) に大文字が使用されます。 ベスト プラクティスとして、カスタム関数の name と id に大文字を使用します。

関数の name は、次と同じにしないでください。

名前付けの競合

関数 name が、既に存在するアドインの関数 name と同じ場合は、 ブックに #REF! エラーが表示されます。

名前付けの競合を解決するには、アドインの name を変更して、関数をもう一度試します。 競合する名前のアドインをアンインストールすることもできます。 または、異なる環境でアドインをテストする場合は、別の名前空間を使用して関数 ( NAMESPACE_NAMEOFFUNCTION など) を区別してみてください。

ベスト プラクティス

  • 同じ名前または類似の名前を持つ複数の関数を作成するのではなく、関数に複数の引数を追加することを検討してください。
  • 関数名のあいまいな省略形は避けてください。 簡潔さよりも明確さが重要です。 =INCではなく、=INCREASETIMEのような名前を選択します。
  • 関数名は、ZIPCODE ではなく =GETZIPCODE などの関数のアクションを示す必要があります。
  • 同様のアクションを実行する関数には、同じ動詞を一貫して使用します。 たとえば、=DELETEZIPCODEや=REMOVEADDRESSではなく、=DELETEZIPCODEと=DELETEADDRESSを使用します。
  • ストリーミング関数に名前を付ける場合は、関数の説明でその旨にメモを追加するか、関数の名前の末尾に STREAM を追加することを検討してください。

ヒント

複数の環境 (開発、ステージング、デモなど) でアドインをテストする場合は、環境ごとに異なるマニフェスト ファイルを維持することをお勧めします。 各マニフェスト ファイルでは、次のことができます。

  • 環境に対応する URL を指定します。
  • Resources 内の DisplayName やラベルなどのメタデータ値をカスタマイズして環境を示し、エンド ユーザーがサイドロードされたアドインの対応する環境を識別できるようにします。
  • アドインでカスタム関数が定義されている場合は、カスタム関数 namespace をカスタマイズして環境を示します。

このガイダンスに従うことで、テスト プロセスを効率化し、アドインが複数の環境で同時にサイドロードされるときに発生する問題を回避します。

カスタム関数をローカライズする

アドインとカスタム関数名の両方をローカライズできます。 そのためには、関数の JSON ファイルにローカライズされた関数名を指定し、アドインのみのマニフェスト ファイルにロケール情報を指定します。

重要

自動生成されたメタデータはローカライズでは機能しないため、JSON ファイルを手動で更新する必要があります。 これを行う方法については、「 カスタム関数の JSON メタデータを手動で作成する」を参照してください。

関数名をローカライズする

カスタム関数をローカライズするには、言語ごとに新しい JSON メタデータ ファイルを作成します。 各言語 JSON ファイルで、ターゲット言語に name プロパティと description プロパティを追加します。 英語の既定のファイルには functions.json という名前が付けられます。 functions-de.json など、 追加の JSON ファイルごとにファイル名のロケールを使用して識別します。

nameとdescriptionは Excel に表示され、ローカライズされています。 ただし、各関数の id はローカライズされません。 id プロパティは、Excel が関数を一意として識別する方法であり、設定後は変更しないでください。

重要

ローカライズされた関数と競合するため、関数に別の言語の組み込み Excel 関数である id または name を与えないようにします。

次の JSON は、 id プロパティ "MULTIPLY" を使用して関数を定義する方法を示しています。 関数の name プロパティと description プロパティは、ドイツ語用にローカライズされています。 各パラメーター name と description もドイツ語用にローカライズされています。

{
    "id": "MULTIPLY",
    "name": "SUMME",
    "description": "Summe zwei Zahlen",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "eins",
            "description": "Erste Nummer",
            "dimensionality": "scalar"
        },
        {
            "name": "zwei",
            "description": "Zweite Nummer",
            "dimensionality": "scalar"
        },
    ],
}

前の JSON と英語の次の JSON を比較します。

{
    "id": "MULTIPLY",
    "name": "Multiply",
    "description": "Multiplies two numbers",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "one",
            "description": "first number",
            "dimensionality": "scalar"
        },
        {
            "name": "two",
            "description": "second number",
            "dimensionality": "scalar"
        },
    ],
}

アドインをローカライズする

言語ごとに JSON ファイルを作成した後、アドインのみのマニフェスト ファイルを、各 JSON メタデータ ファイルの URL を指定するロケールごとのオーバーライド値で更新します。 次のマニフェスト XML は、既定の en-us ロケールと、 de-de (ドイツ) のオーバーライド JSON ファイル URL を示しています。 functions-de.json ファイルには、ローカライズされたドイツ語の関数名と ID が含まれています。

<DefaultLocale>en-us</DefaultLocale>
...
<Resources>
     <bt:Urls>
        <bt:Url id="Contoso.Functions.Metadata.Url" DefaultValue="https://localhost:3000/dist/functions.json"/>
          <bt:Override Locale="de-de" Value="https://localhost:3000/dist/functions-de.json" />
        </bt:url>
        
     </bt:Urls>
</Resources>

アドインをローカライズするプロセスの詳細については、「 Office アドインのローカライズ」を参照してください。

次の手順

エラー処理のベスト プラクティスについて説明します。

関連項目