Beispiel für Das Lokalisieren von Ui-Elementen in SharePoint-Add-In

Das Beispiel-Add-In Core.JavaScriptCustomization zeigt, wie Sie javaScript verwenden, um den Textwert eines SharePoint-UI-Elements durch einen übersetzten Textwert zu ersetzen, der aus einer JavaScript-Ressourcendatei gelesen wird.

Hinweis

Sie sind für die Verwaltung der übersetzten Textwerte in der JavaScript-Ressourcendatei verantwortlich.

Wichtig

JSLink-basierte Anpassungen (clientseitige Darstellung) werden in modernen Benutzeroberflächen nicht unterstützt. Dies umfasst moderne Listen und Bibliotheken, einschließlich JSLink-Unterstützung in den Listenansichts-Webparts der modernen Seiten. Die clientseitige Darstellung wird in den klassischen Benutzeroberflächen in SharePoint Online oder lokal unterstützt.

In diesem Codebeispiel wird ein vom Anbieter gehostetes Add-In für Folgendes verwendet:

• Lokalisieren Sie den Titel einer Websiteseite oder eines Schnellstartlinks mit bestimmten Textwerten.
• Behalten Sie den Titel einer Websiteseite oder eines Schnellstartlinks in einer primären Sprache bei, und stellen Sie zur Laufzeit übersetzte Versionen der Websiteseite und des Titels des Schnellstartlinks in einer anderen Sprache bereit.
• Verwenden Sie JavaScript-Ressourcendateien für die clientseitige Lokalisierung.
• Verknüpfen Einer JavaScript-Datei mit einer SharePoint-Website mithilfe einer benutzerdefinierten Aktion.
• Überprüfen Sie die Benutzeroberflächenkultur der Website, und laden Sie dann kulturspezifische Textwerte aus einer JavaScript-Ressourcendatei.
• Überschreiben Sie Websiteseiten- und Schnellstartlinktitel mit kulturspezifischen Textwerten mithilfe von jQuery.

Bevor Sie beginnen

Laden Sie zunächst das Beispiel-Add-In Core.JavaScriptCustomization aus dem Projekt Office 365 Developer patterns and practices (Entwicklermuster und -methoden) auf GitHub herunter.

Bevor Sie dieses Codebeispiel ausführen, führen Sie die folgenden Schritte aus.

Konfigurieren der Spracheinstellungen auf Ihrer Website

1. Wählen Sie auf Ihrer Teamwebsite Einstellungen>Websiteeinstellungen aus.

2. Wählen Sie unter Websiteverwaltungdie Option Spracheinstellungen aus.

3. Wählen Sie auf der Seite Spracheinstellungen unter Alternative Sprachen die alternativen Sprachen aus, die Ihre Website unterstützen soll. Wählen Sie beispielsweise Finnisch und Französisch aus, wie in der folgenden Abbildung dargestellt.

   

4. Wählen Sie OK aus.

Festlegen der Anzeigesprache auf der Profilseite Ihres Benutzers

1. Wählen Sie Ihr Profilbild oben auf Ihrer Office 365-Website aus, und wählen Sie dann Über mich aus.

   

2. Wählen Sie auf der Seite Über mich die Option Profil bearbeiten aus.

3. Wählen Sie die Auslassungspunkte (...) für zusätzliche Optionen aus, und wählen Sie dann Sprache und Region aus.

4. Wählen Sie unter Meine Anzeigesprachen in der Liste Neue Sprache auswählen eine neue Sprache aus, und wählen Sie dann Hinzufügen aus. Wählen Sie beispielsweise Finnisch und Französisch aus. Sie können Ihre bevorzugte Sprache nach oben oder unten verschieben, indem Sie die NACH-OBEN- und NACH-UNTEN-TASTE auswählen.

   

5. Klicken Sie auf Alles speichern und schließen.

Hinweis

Es kann einige Minuten dauern, bis Ihre Website in den ausgewählten Sprachen gerendert wurde.

Wichtig

Das CSOM wird in regelmäßigen Abständen mit neuen Features aktualisiert. Wenn das CSOM neue Features zum Aktualisieren von Websiteseiten- oder Schnellstartlinktiteln bereitstellt, wird empfohlen, die neuen Features im CSOM anstelle der hier erläuterten Optionen zu verwenden.

Bevor Sie Szenario 2 dieses Codebeispiels ausführen, führen Sie die folgenden Aufgaben aus.

Erstellen eines Schnellstartlinks

1. Wählen Sie im Hostweb LINKS BEARBEITEN aus.

2. Wählen Sie link aus.

   

3. Geben Sie unter Anzuzeigenden Textden Eintrag Mein Quicklaunch-Eintrag ein.

4. Geben Sie unter Adresse die URL einer Website ein.

5. Klicken Sie auf OK>Speichern.

Erstellen einer Websiteseite

1. Wählen Sie im Hostweb Websiteinhalte>Websiteseiten>Neu aus.
2. Geben Sie unter Neuer Seitennameden Namen Hello SharePoint ein.
3. Wählen Sie Erstellen.
4. Geben Sie die Seite Test in den Textkörper der Seite ein.
5. Wählen Sie Speichern aus.

Ausführen der Core.JavaScriptCustomization-Beispiel-App

Wenn Sie dieses Codebeispiel ausführen, wird eine vom Anbieter gehostete Anwendung angezeigt, wie in der folgenden Abbildung dargestellt. In diesem Artikel werden Szenario 1 und Szenario 2 beschrieben, da Sie die Techniken in diesen beiden Szenarien verwenden können, um lokalisierte Versionen Ihrer Websiteseite und Schnellstartlinktitel bereitzustellen.

Szenario 1

Szenario 1 zeigt, wie Sie mithilfe einer benutzerdefinierten Aktion einen Verweis auf eine JavaScript-Datei auf einer SharePoint-Website hinzufügen. Wenn Sie die Schaltfläche Anpassung einfügen auswählen, wird die btnSubmit_Click-Methode in scenario1.aspx.cs aufgerufen. Die btnSubmit_Click-Methode ruft AddJsLink auf, um Verweise auf JavaScript-Dateien mithilfe einer benutzerdefinierten Aktion im Hostweb hinzuzufügen.

Die folgende Abbildung zeigt die Startseite für Szenario 1.

Hinweis

Der Code in diesem Artikel wird wie besehen und ohne jegliche Garantie zur Verfügung gestellt, gleich ob ausdrücklich oder konkludent, einschließlich jedweder stillschweigenden Gewährleistung der Eignung für einen bestimmten Zweck, Marktgängigkeit oder Nichtverletzung von Rechten.

Die AddJSLink-Methode ist Teil der Datei JavaScriptExtensions.cs in OfficeDevPnP.Core. AddJSLink erfordert, dass Sie eine Zeichenfolge angeben, die den Bezeichner darstellt, der der benutzerdefinierten Aktion zugewiesen werden soll, und eine Zeichenfolge, die eine durch Semikolons getrennte Liste von URLs zu den JavaScript-Dateien enthält, die Sie dem Hostweb hinzufügen möchten. Beachten Sie, dass in diesem Codebeispiel ein Verweis auf Scripts\scenario1.js hinzugefügt wird, der dem Hostweb eine status Balkenmeldung hinzufügt.

protected void btnSubmit_Click(object sender, EventArgs e)
{
  var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
  using (var cc = spContext.CreateUserClientContextForSPHost())
  {
      cc.Web.AddJsLink(Utilities.Scenario1Key, Utilities.BuildScenarioJavaScriptUrl(Utilities.Scenario1Key, this.Request));
  }
}

Hinweis

SharePoint verwendet die Minimale Downloadstrategie, um die Datenmenge zu reduzieren, die der Browser herunterlädt, wenn Benutzer zwischen Seiten auf einer SharePoint-Website navigieren. In scenario1.js stellt der folgende Code sicher, dass unabhängig davon, ob die Minimale Downloadstrategie auf Ihrer SharePoint-Website verwendet wird, die RemoteManager_Inject-Methode immer aufgerufen wird, um den JavaScript-Code zum Hinzufügen der status leistenmeldung zum Hostweb auszuführen. Weitere Informationen finden Sie unter Minimal Downloadstrategie – Übersicht.

if ("undefined" != typeof g_MinimalDownload && g_MinimalDownload && (window.location.pathname.toLowerCase()).endsWith("/_layouts/15/start.aspx") && "undefined" != typeof asyncDeltaManager) {
    // Register script for MDS if possible.
    RegisterModuleInit("scenario1.js", RemoteManager_Inject); //MDS registration
    RemoteManager_Inject(); //non MDS scenario
} else {
    RemoteManager_Inject();
}

Hinweis

Einige JavaScript-Dateien hängen möglicherweise von anderen JavaScript-Dateien ab, die zuerst geladen werden müssen, bevor sie ausgeführt und erfolgreich abgeschlossen werden können. Das folgende Codekonstrukt aus RemoteManager_Inject verwendet die loadScript-Funktion in scenario1.js, um zuerst jQuery zu laden, und setzt dann die Ausführung des verbleibenden JavaScript-Codes fort.

var jQuery = "https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.2.min.js";
    // Load jQuery first, and then continue running the rest of the code.
    loadScript(jQuery, function () {
    // Add additional JavaScript code here to complete your task.
});

Wählen Sie Zurück zur Website aus. Wie in der folgenden Abbildung dargestellt, zeigt das Hostweb jetzt eine status Balkenmeldung an, die von scenario1.js hinzugefügt wurde.

Szenario 2

Szenario 2 verwendet das in Szenario 1 beschriebene Verfahren, um Benutzeroberflächentext durch übersetzten Text zu ersetzen, der aus einer JavaScript-Ressourcendatei gelesen wird. Szenario 2 ersetzt den Titel des Schnellstartlinks (Mein Quicklaunch-Eintrag) und den Websiteseitentitel (Hello SharePoint), die Sie zuvor erstellt haben. Szenario 2 fügt eine JavaScript-Datei an, die übersetzte Textwerte aus Variablen in kulturspezifischen JavaScript-Ressourcendateien liest. Szenario 2 aktualisiert dann die Benutzeroberfläche.

Die folgende Abbildung zeigt die Startseite für Szenario 2.

Wie gezeigt, werden beim Auswählen von Anpassung einfügen die folgenden Änderungen auf die Website angewendet:

• Der Schnellstartlink mit dem Titel Mein Schnellstarteintrag wird in Contoso-Link geändert.

• Der Titel der Seite Hello SharePoint-Website wird in Contoso-Seite geändert.

  

Hinweis

Wenn ihre Werte für den Titel des Schnellstartlinks und den Websiteseitentitel von den werten in der vorherigen Abbildung abweichen, bearbeiten Sie die variablen quickLauch_Scenario2 und pageTitle_HelloSharePoint in der JavaScript-Ressourcendatei scenario2.en-us.js oder scenario2.nl-nl.js, und führen Sie dann das Codebeispiel erneut aus.

In der scenario2.en-us.js-Datei werden kulturspezifische Ressourcen für Englisch (USA) gespeichert. Die scenario2.nl-nl.js Datei speichert niederländische kulturspezifische Ressourcen. Wenn Sie dieses Codebeispiel mit einer anderen Sprache testen, sollten Sie eine weitere JavaScript-Ressourcendatei erstellen, die dieselbe Namenskonvention verwendet.

Ähnlich wie in Szenario 1 ruft btnSubmit_Click in scenario2.aspx.cs AddJsLink auf, um einen Verweis auf die Scripts\scenario2.js-Datei hinzuzufügen. In scenario2.js ruft die funktion RemoteManager_Inject die TranslateQuickLaunch-Funktion auf, die die folgenden Aufgaben ausführt:

• Bestimmt die Kultur der Website mithilfe von _spPageContextInfo.currentUICultureName.
• Lädt die JavaScript-Ressourcendatei mit kulturspezifischen Ressourcen, die der Benutzeroberflächenkultur der Website entsprechen. Wenn die Kultur der Website beispielsweise englisch (USA) war, wird die scenario2.en-us.js Datei geladen.
• Ersetzt meinen Quicklaunch-Eintrag durch den Wert der aus der JavaScript-Ressourcendatei gelesenen quickLauch_Scenario2 Variablen.

function RemoteManager_Inject() {
    var jQuery = "https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.2.min.js";

    loadScript(jQuery, function () {
        SP.SOD.executeOrDelayUntilScriptLoaded(function () { TranslateQuickLaunch(); }, 'sp.js');
    });
}

function TranslateQuickLaunch() {
    // Load jQuery and if complete, load the JS resource file.
    var scriptUrl = "";
    var scriptRevision = "";
    // Iterate over the scripts loaded on the page to find the scenario2 script. Then use the script URL to dynamically build the URL for the resource file to be loaded.
    $('script').each(function (i, el) {
        if (el.src.toLowerCase().indexOf('scenario2.js') > -1) {
            scriptUrl = el.src;
            scriptRevision = scriptUrl.substring(scriptUrl.indexOf('.js') + 3);
            scriptUrl = scriptUrl.substring(0, scriptUrl.indexOf('.js'));
        }
    })

    var resourcesFile = scriptUrl + "." + _spPageContextInfo.currentUICultureName.toLowerCase() + ".js" + scriptRevision;
    // Load the JS resource file based on the user's language settings.
    loadScript(resourcesFile, function () {

        // General changes that apply to all loaded pages.
        // ----------------------------------------------

        // Update the Quick Launch labels.
        // Note that you can use the jQuery  function to iterate over all elements that match your jQuery selector.
        $("span.ms-navedit-flyoutArrow").each(function () {
            if (this.innerText.toLowerCase().indexOf('my quicklaunch entry') > -1) {
                // Update the label.
                $(this).find('.menu-item-text').text(quickLauch_Scenario2);
                // Update the tooltip.
                $(this).parent().attr("title", quickLauch_Scenario2);
            }
        });

        // Page-specific changes require an IsOnPage call.
        // ----------------------------------------------------------

        // Change the title of the "Hello SharePoint" page.
        if (IsOnPage("Hello%20SharePoint.aspx")) {
            $("#DeltaPlaceHolderPageTitleInTitleArea").find("A").each(function () {
                if ($(this).text().toLowerCase().indexOf("hello sharepoint") > -1) {
                    // Update the label.
                    $(this).text(pageTitle_HelloSharePoint);
                    // Update the tooltip.
                    $(this).attr("title", pageTitle_HelloSharePoint);
                }
            });
        }

    });
}

Siehe auch

• Enterprise Content Management-Lösungen für SharePoint
• Lokalisierungslösungen für SharePoint