Teilen über

Benennung und Lokalisierung von benutzerdefinierten Funktionen

Dieser Artikel enthält Richtlinien und bewährte Methoden für die Benennung benutzerdefinierter Funktionen und erläutert, wie sie lokalisiert werden.

Namensrichtlinien für benutzerdefinierte Funktionen

Eine benutzerdefinierte Funktion wird durch und idname in den JSON-Metadaten identifiziert.

  • id: Eindeutiger Bezeichner, der im Code verwendet wird.
  • name: Anzeigename, der benutzern angezeigt wird. Sie kann lokalisiert werden.

Wichtig

Beachten Sie, dass benutzerdefinierte Excel-Funktionen auf den folgenden Plattformen verfügbar sind.

  • Office im Web
  • Office unter Windows
    • Microsoft 365-Abonnement
    • retail unbefristete Office 2016 und höher
    • volumelizenzierte unbefristete/LTSC-Office 2021 und höher
  • Office für Mac

Benutzerdefinierte Excel-Funktionen werden derzeit in den folgenden Artikeln nicht unterstützt:

  • Office auf dem iPad
  • Volumenlizenzierte unbefristete Versionen von Office 2021 oder früher unter Windows

Hinweis

Das einheitliche Manifest für Microsoft 365 unterstützt derzeit keine Projekte für benutzerdefinierte Funktionen. Sie müssen das Add-In-Manifest nur für projekte mit benutzerdefinierten Funktionen verwenden. Weitere Informationen finden Sie unter Office-Add-Ins-Manifest.

Eine Funktion name kann sich von der für die id Lokalisierung unterscheiden. Wenn Sie keine Lokalisierung benötigen, empfiehlt es sich, für beide Denselben Wert zu verwenden.

Eine Funktion name und id teilen einige ähnliche Regeln.

  • Beide müssen mit einem Buchstaben beginnen und mindestens drei Zeichen umfassen.
  • id: Nur A–Z, 0–9, Unterstriche und Punktzeichen sind zulässig.
  • name: Alle Unicode-Alphabetzeichen, Unterstriche und Punktzeichen sind zulässig.

Excel zeigt integrierte Funktionsnamen in Großbuchstaben an (z. B SUM. ). Verwenden Sie Großbuchstaben für Ihre benutzerdefinierten Funktionen, damit sie sich auf natürliche Weise einfügen können.

Vermeiden Sie Namen, die übereinstimmen:

Benennungskonflikte

Wenn Ihre Funktion name mit einem anderen Add-In in Konflikt kommt, zeigt Excel den Fehler #REF! an.

Beheben Sie Konflikte, indem Sie Ihre Funktion umbenennen oder das andere Add-In deinstallieren. Verwenden Sie für Tests in mehreren Umgebungen ein kurzes Namespacepräfix (z ADDINNAME_FUNCTIONNAME. B. ).

Bewährte Methoden

  • Verwenden Sie zusätzliche Funktionsargumente, anstatt mehrere ähnliche Funktionsnamen zu erstellen. beispielsweise GETNAME(firstName, middleName, lastName) ist effizienter als separate Funktionen wie GETFIRSTNAME, GETMIDDLENAMEund GETLASTNAME.
  • Vermeiden Sie Abkürzungen, die nicht klar sind. Ist beispielsweise INCREASETIME einfacher zu verstehen als INC.
  • Wählen Sie Aktionsverben für Funktionsnamen aus. Verwenden Sie GETZIPCODE anstelle von ZIPCODE.
  • Seien Sie konsistent. Verwenden Sie dasselbe Verb für ähnliche Aktionen, z DELETEZIPCODE . B. und DELETEADDRESS.
  • Fügen Sie STREAM für Streamingfunktionen dem Namen hinzu, oder fügen Sie eine Notiz in die Beschreibung ein.
  • Verwenden Sie ein kurzes Anbieterpräfix in Ihren Funktionsnamen, um Konflikte mit anderen Add-Ins zu vermeiden. Verwenden Sie z. B. CONTOSO_GETPRICE oder CONTOSO_TAX_CALC.

Tipp

Wenn Sie Ihr Add-In in mehreren Umgebungen (z. B. in der Entwicklung, im Staging, in der Demo usw.) testen, empfehlen wir Ihnen, für jede Umgebung eine andere Manifestdatei zu verwalten. In jeder Manifestdatei haben Sie folgende Möglichkeiten:

  • Geben Sie die URLs an, die der Umgebung entsprechen.

  • Passen Sie Metadatenwerte an, damit Endbenutzer die entsprechende Umgebung eines quergeladenen Add-Ins identifizieren können. Zum Beispiel:

    • Passen Sie im einheitlichen Manifest für Microsoft 365 die "name" Eigenschaft des Add-Ins und die "label" Eigenschaften für verschiedene Benutzeroberflächensteuerelemente an, um die Umgebung anzugeben.
    • Passen Sie im reinen Add-In-Manifest die DisplayName Bezeichnungen element und und innerhalb des Resources Elements an, um die Umgebung anzugeben.

  • Passen Sie die benutzerdefinierten Funktionen namespace an, um die Umgebung anzugeben, wenn Ihr Add-In benutzerdefinierte Funktionen definiert.

Durch Befolgen dieser Anleitung optimieren Sie den Testprozess und vermeiden Probleme, die andernfalls auftreten würden, wenn ein Add-In für mehrere Umgebungen gleichzeitig quergeladen wird.

Kurzübersicht zu Benennungseinschränkungen

Anleitung id name Hinweise
Zulässige Zeichen A–Z 0–9 _. Unicode alphabetische Zeichen _. Einfach bleiben id . Lokalisieren Sie name.
Muss mit einem Buchstaben beginnen Ja Ja Vermeidet Zellbezugsverwechslungen.
Mindestlänge 3 3 Kurznamen verringern die Übersichtlichkeit.
Großschreibung Alle empfohlenen Großbuchstaben Alle empfohlenen Großbuchstaben Entspricht der Excel-Formatvorlage.
Lokalisierbar Nein Ja Bleiben Sie id stabil. Lokalisieren Sie sie name nach Bedarf.
Kann die Zelladresse imitieren Nein Nein Verhindern von Adressanalysefehlern.
Reservierte Makronamen Unzulässige Unzulässige Einige Beispiele: RUN, ECHO.

Lokalisieren von benutzerdefinierten Funktionen

Sie können sowohl Ihr Add-In als auch Ihre benutzerdefinierten Funktionsnamen lokalisieren. Fügen Sie lokalisierte Funktionsnamen in Ihrer JSON-Datei hinzu, und legen Sie Gebietsschemaüberschreibungen nur im Add-In-Manifest fest.

Wichtig

Automatisch generierte Metadaten funktionieren nicht für die Lokalisierung, sodass Sie die JSON-Datei manuell aktualisieren müssen. Informationen dazu finden Sie unter Manuelles Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen.

Lokalisieren von Funktionsnamen

Um Ihre benutzerdefinierten Funktionen zu lokalisieren, erstellen Sie eine separate JSON-Metadatendatei für jede Sprache. Fügen Sie in jeder Datei die name Eigenschaften und description in der Zielsprache hinzu. Verwenden Sie functions.json für Englisch, und fügen Sie das Gebietsschema in den Dateinamen für andere Sprachen ein, z . B. functions-de.json für Deutsch.

Excel lokalisiert nur die name Eigenschaften und description . ist id nicht lokalisiert und sollte nach dem Festlegen unverändert bleiben.

Wichtig

Vermeiden Sie ein id oder name , das mit einer integrierten Excel-Funktion in einer beliebigen Sprache übereinstimmt.

Der folgende JSON-Code zeigt, wie eine Funktion mit der id Eigenschaft "MULTIPLY" definiert wird. Die name - und description -Eigenschaft der Funktion ist für Deutsch lokalisiert. Jeder Parameter name und description ist auch für Deutsch lokalisiert.

{
    "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"
        }
    ]
}

Vergleichen Sie den vorherigen JSON-Code mit dem folgenden JSON-Code für Englisch.

{
    "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"
        }
    ]
}

Lokalisieren Ihres Add-Ins

Nachdem Sie einen JSON-Code für jede Sprache erstellt haben, fügen Sie dem Add-In-Manifest nur eine Außerkraftsetzung hinzu, die auf die richtige Datei verweist. Der folgende Manifest-XML-Code zeigt ein Standardgebietsschema en-us sowie eine AUßERKRAFTSETZUNGs-JSON-Datei-URL für de-de (Deutschland).

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

Weitere Informationen zum Lokalisieren eines Add-Ins finden Sie unter Lokalisierung für Office-Add-Ins.

Nächste Schritte

Erfahren Sie mehr über bewährte Methoden zur Fehlerbehandlung.

Siehe auch

  • Last updated on