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

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

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

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

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

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

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

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

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

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

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

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

• A1 から XFD1048576 までのセル、または R1C1 から R1048576C16384 までのセル。

• Excel 4.0 マクロ関数 (、 ECHOなどRUN)。 これらの関数の完全な一覧については、 こちらの Excel マクロ関数リファレンス ドキュメントを参照してください。

名前付けの競合

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

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

ベスト プラクティス

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

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

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

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

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

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

次の JSON は、プロパティ "MULTIPLY" を使用して関数を定義する方法を id 示しています。 name関数の and 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 マニフェスト ファイルを更新します。 次のマニフェスト XML は、(Germany) のオーバーライド JSON ファイル URL を持つ既定 en-us のロケールを de-de 示しています。 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 アドインのローカライズ」を参照してください。

次の手順

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

関連項目

• カスタム関数の JSON メタデータを手動で作成する
• Excel カスタム関数のチュートリアル