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

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

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

カスタム関数は、JSON メタデータの id と name によって識別されます。

id: コードで使用される一意の識別子。
name: ユーザーに表示される表示名。ローカライズできます。

重要

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 アドインマニフェスト」を参照してください。

関数 name は、ローカライズの id とは異なる場合があります。ローカライズが必要ない場合は、両方に同じ値を使用することをお勧めします。

関数の name と id は、いくつかの同様の規則を共有します。

どちらも文字で始まり、少なくとも 3 文字である必要があります。
id: A から Z、0 ~ 9、アンダースコア、ピリオドの文字のみを使用できます。
name: Unicode アルファベット、アンダースコア、ピリオド文字を使用できます。

Excel では、組み込みの関数名が大文字で表示されます (たとえば、 SUM)。カスタム関数に大文字を使用して、自然に組み込むのに役立ちます。

一致する名前は避けてください。

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

名前付けの競合

関数 name 別のアドインのアドインと競合している場合は、 #REF! エラーが表示されます。

関数の名前を変更するか、他のアドインをアンインストールして競合を修正します。複数の環境でテストする場合は、短い名前空間プレフィックス ( ADDINNAME_FUNCTIONNAME など) を使用します。

ベストプラクティス

類似する複数の関数名を作成する代わりに、追加の関数引数を使用します。たとえば、 GETNAME(firstName, middleName, lastName) は、 GETFIRSTNAME、 GETMIDDLENAME、 GETLASTNAMEなどの個別の関数を持つよりも効率的です。
明確でない省略形は避けてください。たとえば、 INCREASETIME は INCよりもわかりやすいです。
関数名のアクション動詞を選択します。 ZIPCODEではなく、GETZIPCODEを使用します。
一貫性を持たせます。 DELETEZIPCODEやDELETEADDRESSなど、同様のアクションには同じ動詞を使用します。
ストリーミング関数の場合は、名前に STREAM を追加するか、説明にメモを含めます。
他のアドインとの競合を回避するには、関数名に短いベンダープレフィックスを使用します。たとえば、 CONTOSO_GETPRICE または CONTOSO_TAX_CALCを使用します。

ヒント

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

環境に対応する URL を指定します。
エンドユーザーがサイドロードされたアドインの対応する環境を識別できるように、メタデータ値をカスタマイズします。例:
- Microsoft 365 の統合マニフェストで、アドインの "name" プロパティと、環境を示すさまざまな UI コントロールの "label" プロパティをカスタマイズします。
- アドインのみのマニフェストで、 DisplayName 要素と Resources 要素内のラベルをカスタマイズして、環境を示します。
アドインでカスタム関数が定義されている場合は、カスタム関数 namespace をカスタマイズして環境を示します。

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

名前付け制約のクイックリファレンス

Guideline	`id`	`name`	備考
使用できる文字	A – Z 0 – 9 `_.`	Unicode アルファベット `_.`	`id`シンプルにしてください。 `name`をローカライズします。
文字で始まる必要があります	はい	はい	セル参照の混乱を回避します。
最小長さ	3	3	短い名前を使用すると、わかりやすさが低下します。
大文字化	すべての大文字をお勧めします	すべての大文字をお勧めします	Excel スタイルと一致します。
ローカライズ	不要	はい	`id`安定したままにしてください。必要に応じて `name` をローカライズします。
セルアドレスを模倣できます	不要	不要	アドレス解析エラーを防ぎます。
予約済みマクロ名	禁止	禁止	いくつかの例: `RUN`、 `ECHO`。

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

アドインとカスタム関数名の両方をローカライズできます。ローカライズされた関数名を JSON ファイルに追加し、アドインのみのマニフェストでロケールのオーバーライドを設定します。

重要

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

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

カスタム関数をローカライズするには、言語ごとに個別の JSON メタデータファイルを作成します。各ファイルに、ターゲット言語で name プロパティと description プロパティを追加します。英語 には functions.json を使用し、ドイツ語の functions-de.json など、他の言語のファイル名にロケールを含めます。

Excel では、 name プロパティと description プロパティのみがローカライズされます。 idはローカライズされず、設定後も変更されません。

重要

任意の言語の組み込み 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 を作成した後、正しいファイルを指すアドインのみのマニフェストにオーバーライドを追加します。次のマニフェスト XML は、既定の en-us ロケールに加えて、 de-de (ドイツ) のオーバーライド JSON ファイル URL を示しています。

<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 アドインのローカライズ」を参照してください。

次の手順

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

フィードバック

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

Last updated on 2025-10-31

次の方法で共有