Benennung und Lokalisierung von benutzerdefinierten Funktionen

  • Artikel

In diesem Artikel werden Richtlinien und bewährte Methoden für die Benennung benutzerdefinierter Funktionen beschrieben. Außerdem wird gezeigt, wie Sie benutzerdefinierte Funktionsnamen in andere Sprachen als Englisch lokalisieren.

Namensrichtlinien für benutzerdefinierte Funktionen

Eine benutzerdefinierte Funktion wird durch eine - und name -idEigenschaft in der JSON-Metadatendatei identifiziert.

  • Die Funktion id wird verwendet, um benutzerdefinierte Funktionen in Ihrem JavaScript-Code eindeutig zu identifizieren.
  • Die Funktion name wird als Anzeigename verwendet, der einem Benutzer in Excel angezeigt wird.

Wichtig

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

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

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

  • Office auf dem iPad
  • Volumenlizenzierte unbefristete Versionen von Office 2019 oder früheren Versionen

Eine Funktion name kann sich von der -Funktion idunterscheiden, z. B. für Lokalisierungszwecke. Im Allgemeinen sollte eine Funktion name gleich bleiben, id wenn es keinen Grund gibt, sich zu unterscheiden.

Eine Funktion name und id teilen einige allgemeine Anforderungen.

  • Eine Funktion id darf nur die Zeichen A bis Z, zahlen 0 bis neun, Unterstriche und Punkte verwenden.

  • Eine Funktion name kann alle alphabetischen Unicode-Zeichen, Unterstriche und Punkte verwenden.

  • Sowohl funktion nameid als auch müssen mit einem Buchstaben beginnen und eine Mindestanzahl von drei Zeichen aufweisen.

Excel verwendet Großbuchstaben für integrierte Funktionsnamen (z SUM. B. ). Verwenden Sie Großbuchstaben für ihre benutzerdefinierten name Funktionen und id als bewährte Methode.

Eine Funktion name sollte nicht mit folgendem identisch sein:

  • Alle Zellen zwischen A1 und XFD1048576 oder alle Zellen zwischen R1C1 und R1048576C16384.

  • Eine beliebige Excel 4.0-Makrofunktion (z RUN. B. , ECHO). Eine vollständige Liste dieser Funktionen finden Sie in diesem Referenzdokument zu Excel-Makrofunktionen.

Benennungskonflikte

Wenn Ihre Funktion name mit einer Funktion name in einem add-in identisch ist, das bereits vorhanden ist, wird der fehler #REF! in Der Arbeitsmappe angezeigt.

Um einen Namenskonflikt zu beheben, ändern Sie in Ihrem Add-In, name und versuchen Sie es erneut. Sie können das Add-In auch mit dem in Konflikt stehenden Namen deinstallieren. Oder wenn Sie Ihr Add-In in verschiedenen Umgebungen testen, versuchen Sie, einen anderen Namespace zu verwenden, um Ihre Funktion zu unterscheiden (z NAMESPACE_NAMEOFFUNCTION. B. ).

Bewährte Methoden

  • Erwägen Sie, einer Funktion mehrere Argumente hinzuzufügen, anstatt mehrere Funktionen mit demselben oder ähnlichen Namen zu erstellen.
  • Vermeiden Sie mehrdeutige Abkürzungen in Funktionsnamen. Clarity ist wichtiger als Die Kürze. Wählen Sie einen Namen wie =INCREASETIME statt aus =INC.
  • Funktionsnamen sollten die Aktion der Funktion angeben, z. B. =GETZIPCODE anstelle von ZIPCODE.
  • Verwenden Sie konsistent dieselben Verben für Funktionen, die ähnliche Aktionen ausführen. Verwenden Sie =DELETEZIPCODE beispielsweise und =DELETEADDRESSanstelle =DELETEZIPCODE von und =REMOVEADDRESS.
  • Wenn Sie eine Streamingfunktion benennen, sollten Sie in der Beschreibung der Funktion oder am Ende des Funktionsnamens eine Notiz zu diesem Effekt hinzufügen STREAM .

Tipp

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

  • Geben Sie die URLs an, die der Umgebung entsprechen.
  • Passen Sie Metadatenwerte wie DisplayName und Bezeichnungen in Resources an, um die Umgebung anzugeben, damit Endbenutzer die entsprechende Umgebung eines quergeladenen Add-Ins identifizieren können.
  • 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.

Lokalisieren von benutzerdefinierten Funktionen

Sie können sowohl Ihr Add-In als auch Ihre benutzerdefinierten Funktionsnamen lokalisieren. Geben Sie dazu lokalisierte Funktionsnamen in der JSON-Datei der Funktionen und Gebietsschemainformationen in der XML-Manifestdatei an.

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 neue JSON-Metadatendatei für jede Sprache. Fügen Sie in jeder JSON-Datei der Sprache eigenschaften und description in der Zielsprache hinzuname. Die Standarddatei für Englisch heißt functions.json. Verwenden Sie das Gebietsschema im Dateinamen für jede zusätzliche JSON-Datei, z . B. functions-de.json , um sie zu identifizieren.

und namedescription werden in Excel angezeigt und sind lokalisiert. Die der id einzelnen Funktionen ist jedoch nicht lokalisiert. Mit id der -Eigenschaft identifiziert Excel Ihre Funktion als eindeutig und sollte nach dem Festlegen nicht mehr geändert werden.

Wichtig

Vermeiden Sie es, Ihren Funktionen eine id oder name eine integrierte Excel-Funktion in einer anderen Sprache zu geben, da dies mit lokalisierten Funktionen in Konflikt steht.

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 eine JSON-Datei für jede Sprache erstellt haben, aktualisieren Sie Ihre XML-Manifestdatei mit einem Überschreibungswert für jedes Gebietsschema, der die URL jeder JSON-Metadatendatei angibt. Der folgende Manifest-XML-Code zeigt ein Standardgebietsschema en-us mit einer AUßERkraftsetzungs-JSON-Datei-URL für de-de (Deutschland). Die functions-de.json Datei enthält die lokalisierten deutschen Funktionsnamen und IDs.

<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