Пример надстройки SharePoint для локализации элементов пользовательского интерфейса

Статья
04/08/2023

В примере надстройки Core.JavaScriptCustomization показано, как использовать JavaScript для замены текстового значения элемента пользовательского интерфейса SharePoint переведенным текстовым значением, которое считывается из файла ресурсов JavaScript.

Примечание.

Вы несете ответственность за обслуживание переведенных текстовых значений в файле ресурсов JavaScript.

Важно!

Настройки на основе JSLink (клиентская обработка) не поддерживаются в современном интерфейсе. Это относится к современным спискам и библиотекам, включая поддержку JSLink в веб-частях представления списка современных страниц. Клиентская обработка поддерживается в классических интерфейсах в SharePoint Online или локальной версии.

В этом примере кода надстройка, размещенная у поставщика, используется для:

Локализуйте страницу сайта или заголовок ссылки быстрого запуска с определенными текстовыми значениями.
Сохраните страницу сайта или заголовок ссылки быстрого запуска на основном языке и предоставьте переведенные версии страницы сайта и заголовок ссылки быстрого запуска на другом языке во время выполнения.
Используйте файлы ресурсов JavaScript для локализации на стороне клиента.
Связывание файла JavaScript с сайтом SharePoint с помощью пользовательского действия.
Проверьте язык и региональные параметры пользовательского интерфейса сайта, а затем загрузите текстовые значения, зависящие от языка и региональных параметров, из файла ресурсов JavaScript.
Перезаписать страницу сайта и заголовки ссылок быстрого запуска с помощью jQuery, используя текстовые значения, зависящие от языка и региональных параметров.

Подготовка к работе

Чтобы приступить к работе, скачайте пример надстройки Core.JavaScriptНастройка из проекта шаблонов и методик для разработчиков Office 365 на сайте GitHub.

Перед выполнением этого примера кода выполните следующие действия.

Настройка языковых параметров на сайте

На сайте группы выберите Параметры Параметры>Параметры сайта.
В разделе Администрирование сайта выберите Языковые параметры.
На странице Языковые параметры в разделе Альтернативные языки выберите альтернативные языки, которые должен поддерживать ваш сайт. Например, выберите финский и французский языки, как показано на следующем рисунке.
Нажмите кнопку OK.

Настройка языка интерфейса на странице профиля пользователя

В верхней части сайта Office 365 выберите изображение своего профиля и щелкните Обо мне.
На странице Обо мне выберите Изменить профиль.
Выберите многоточие (...) для дополнительных параметров, а затем выберите Язык и Регион.
В разделе Мои языки интерфейса выберите новый язык в списке Выберите новый язык и нажмите кнопку Добавить. Например, выберите финский и французский языки. Вы можете переместить предпочитаемый язык вверх или вниз, щелкнув стрелки вверх и вниз.
Нажмите кнопку Сохранить все и закрыть.

Примечание.

Отрисовка сайта на выбранных языках может занять несколько минут.

Важно!

CSOM периодически обновляется с новыми функциями. Если CSOM предоставляет новые функции для обновления страницы сайта или заголовков ссылок быстрого запуска , рекомендуется использовать новые функции в CSOM вместо параметров, рассмотренных здесь.

Перед выполнением сценария 2 этого примера кода выполните следующие задачи.

Создание ссылки быстрого запуска

На хост-сайте выберите ИЗМЕНИТЬ ССЫЛКИ.
Выберите ссылку.
В поле Отображаемый текст введите Запись my quicklaunch.
В поле Адрес введите URL-адрес веб-сайта.
Нажмите ОК>Сохранить.

Создание страницы сайта

На хост-сайте выберите Контент>сайта Страницы> сайтаСоздать.
В поле Новое имя страницы введитеHello SharePoint.
Выберите пункт Создать.
Введите тестовую страницу в тексте страницы.
Выберите Сохранить.

Запуск примера приложения Core.JavaScriptНастройка

При выполнении этого примера кода отображается приложение, размещенное у поставщика, как показано на следующем рисунке. В этой статье описаны сценарии 1 и сценарий 2, так как вы можете использовать методы в этих двух сценариях для предоставления локализованных версий страницы сайта и заголовков ссылок быстрого запуска .

Снимок экрана: начальная страница приложения Core.JavaScriptCustomization

Сценарий 1

Сценарий 1 показывает, как добавить ссылку на файл JavaScript на сайте SharePoint с помощью настраиваемого действия. При нажатии кнопки Внедрить настройку вызывается метод btnSubmit_Click в файле scenario1.aspx.cs. Метод btnSubmit_Click вызывает AddJsLink для добавления ссылок на файлы JavaScript с помощью настраиваемого действия на хост-сайте.

На следующем рисунке показана начальная страница сценария 1.

Снимок экрана: начальная страница сценария 1

Примечание.

Код, приведенный в этой статье, предоставляется "как есть" без какой-либо явной или подразумеваемой гарантии, включая подразумеваемые гарантии пригодности для какой-либо цели, для продажи или гарантии отсутствия нарушения прав иных правообладателей.

Метод AddJSLink является частью файла JavaScriptExtensions.cs в OfficeDevPnP.Core. Для addJSLink требуется указать строку, представляющую идентификатор для назначения пользовательскому действию, и строку, содержащую разделенный точкой с запятой список URL-адресов для файлов JavaScript, которые необходимо добавить на хост-сайт. Обратите внимание, что в этом примере кода добавляется ссылка на Scripts\scenario1.js, которая добавляет сообщение строки состояния на хост-сайт.

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));
  }
}

Примечание.

SharePoint использует стратегию минимального скачивания, чтобы уменьшить объем данных, загружаемых браузером при переходе между страницами на сайте SharePoint. В scenario1.js следующий код гарантирует, что если на сайте SharePoint используется стратегия минимального скачивания, всегда вызывается метод RemoteManager_Inject для запуска кода JavaScript для добавления сообщения строки состояния на хост-сайт. Дополнительные сведения см. в статье Обзор стратегии минимальной загрузки.

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

Примечание.

Некоторые файлы JavaScript могут зависеть от других файлов JavaScript, которые будут загружены первыми, прежде чем они смогут успешно запуститься и завершить работу. Следующая конструкция кода из RemoteManager_Inject использует функцию loadScript в scenario1.js, чтобы сначала загрузить jQuery, а затем продолжить выполнение оставшегося кода JavaScript.

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.
});

Выберите пункт Назад к сайту. Как показано на следующем рисунке, на хост-сайте теперь отображается сообщение строки состояния, добавленное scenario1.js.

Снимок экрана: сообщение строки состояния, добавленное на сайт группы с помощью JavaScript

Сценарий 2

Сценарий 2 использует метод, описанный в сценарии 1, для замены текста пользовательского интерфейса переведенным текстом из файла ресурсов JavaScript. Сценарий 2 заменяет заголовок ссылки быстрого запуска (запись my quicklaunch) и заголовок страницы сайта (Hello SharePoint), созданные ранее. Сценарий 2 присоединяет файл JavaScript, который считывает переведенные текстовые значения из переменных в файлах ресурсов JavaScript, зависящих от языка и региональных параметров. Затем сценарий 2 обновляет пользовательский интерфейс.

На следующем рисунке показана начальная страница сценария 2.

Снимок экрана: начальная страница сценария 2

Как показано ниже, при выборе "Внедрить настройку" к сайту применяются следующие изменения:

Ссылка быстрого запускаМоя запись быстрого запуска изменена на ссылку Contoso.
Заголовок страницы сайта Hello SharePoint изменен на страницу Contoso.

Примечание.

Если значения заголовка ссылки быстрого запуска и заголовка страницы сайта отличаются от значений, показанных на предыдущем рисунке, измените quickLauch_Scenario2 и pageTitle_HelloSharePoint переменные в файле ресурсов JavaScript scenario2.en-us.js или scenario2.nl-nl.js, а затем запустите пример кода еще раз.

В файле scenario2.en-us.js хранятся ресурсы, относящиеся к языку и региональным параметрам на английском языке (США). В файле scenario2.nl-nl.js хранятся ресурсы, относящиеся к голландскому языку и региональным параметрам. Если вы тестируете этот пример кода с помощью другого языка, рассмотрите возможность создания другого файла ресурсов JavaScript, использующего то же соглашение об именовании.

Как и в сценарии 1, btnSubmit_Click в файле scenario2.aspx.cs вызывает Метод AddJsLink , чтобы добавить ссылку на файл Scripts\scenario2.js. В scenario2.js функция RemoteManager_Inject вызывает функцию TranslateQuickLaunch , которая выполняет следующие задачи:

Определяет язык и региональные параметры сайта с помощью _spPageContextInfo.currentUICultureName.
Загружает файл ресурсов JavaScript, содержащий ресурсы, относящиеся к языку и региональным параметрам, которые соответствуют языку пользовательского интерфейса сайта. Например, если язык и региональные параметры сайта были английский (США), загружается файл scenario2.en-us.js.
Заменяет запись быстрого запуска значением переменной quickLauch_Scenario2 , считываемой из файла ресурсов JavaScript.

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);
                }
            });
        }

    });
}

Поделиться через

Пример надстройки SharePoint для локализации элементов пользовательского интерфейса

Подготовка к работе

Настройка языковых параметров на сайте

Настройка языка интерфейса на странице профиля пользователя

Создание ссылки быстрого запуска

Создание страницы сайта

Запуск примера приложения Core.JavaScriptНастройка

Сценарий 1

Сценарий 2

См. также

Дополнительные ресурсы