Создать страницу конфигурацииCreate a configuration page

Страница конфигурации — это особый тип страницы контента , позволяющий пользователям настраивать некоторые аспекты приложения Teams.A configuration page is a special type of content page that allows your users to configure some aspect of your Teams app. Обычно они используются в качестве части:Typically these are used as part of:

Настройка вкладки канала или группового чатаConfiguring a channel or group chat tab

Страница конфигурации информирует страницу содержимого о том, как она должна отображаться.A configuration page informs the content page how it should render. Ваше приложение должно ссылаться на клиентский пакет SDK и вызов Microsoft Teams JavaScript microsoft.initialize() .Your application must reference the Microsoft Teams JavaScript client SDK and call microsoft.initialize(). Кроме того, ваш URL-адрес должен быть защищенными конечными точками HTTPS и доступен в облаке.Additionally, your URLs must be secure HTTPS endpoints and available from the cloud. Ниже приведен пример страницы конфигурации.Below is a configuration page example.

<head>
<script src='https://statics.teams.cdn.office.net/sdk/v1.6.0/js/MicrosoftTeams.min.js'></script>
</head>
    <body>
        <button onclick="(document.getElementById('icon').src = '/images/iconGray.png'); colorClickGray()">Select Gray</button>
        <img id="icon" src="/images/teamsIcon.png" alt="icon" style="width:100px" />
        <button onclick="(document.getElementById('icon').src = '/images/iconRed.png'); colorClickRed()">Select Red</button>

        <script>
            microsoftTeams.initialize();
            let saveGray = () => {
                microsoftTeams.settings.registerOnSaveHandler((saveEvent) => {
                    microsoftTeams.settings.setSettings({
                        websiteUrl: "https://yourWebsite.com",
                        contentUrl: "https://yourWebsite.com/gray",
                        entityId: "grayIconTab",
                        suggestedDisplayName: "MyNewTab"
                    });
                    saveEvent.notifySuccess();
                });
            }
            let saveRed = () => {
                microsoftTeams.settings.registerOnSaveHandler((saveEvent) => {
                    microsoftTeams.settings.setSettings({
                        websiteUrl: "https://yourWebsite.com",
                        contentUrl: "https://yourWebsite.com/red",
                        entityId: "redIconTab",
                        suggestedDisplayName: "MyNewTab"
                    });
                    saveEvent.notifySuccess();
                });
            }

            let gr = document.getElementById("gray").style;
            let rd = document.getElementById("red").style;

            const colorClickGray = () => {
                gr.display = "block";
                rd.display = "none";
                microsoftTeams.settings.setValidityState(true);
                saveGray()
            }

            const colorClickRed = () => {
                rd.display = "block";
                gr.display = "none";
                microsoftTeams.settings.setValidityState(true);
                saveRed();
            }
        </script>
    </body>
...

Здесь у пользователя есть два переключателя, выберите серый или красный , чтобы отобразить содержимое вкладки с помощью значка красного или серого.Here, the user is presented with two option buttons, Select Gray or Select Red to display the tab content with either a red or gray icon. При нажатии кнопки относитель срабатывает saveGray() или saveRed() вызывается следующее:Choosing the relative button fires saveGray() or saveRed() and invokes the following:

  1. settings.setValidityState(true)Для параметра задано значение true.The settings.setValidityState(true) is set to true.
  2. microsoftTeams.settings.registerOnSaveHandler()Запускается обработчик событий.The microsoftTeams.settings.registerOnSaveHandler() event handler is triggered.
  3. Кнопка сохранить на странице настройки приложения, отправленная в Teams, включена.The Save button on the app's configuration page, uploaded in Teams, is enabled.

С помощью этого кода Teams вы узнаете, что требования к конфигурации выполнены, и установка может быть продолжена.This code lets Teams know that the configuration requirements have been satisfied and the installation can proceed. При сохранениипараметры settings.setSettings() задаются, как определено Settings интерфейсом, для текущего экземпляра (см. интерфейс параметров ).On Save, the parameters of settings.setSettings() are set, as defined by the Settings interface, for the current instance (See Settings interface ). Finally saveEvent.notifySuccess() вызывается, чтобы показать, что URL-адрес контента успешно разрешен.Finally, saveEvent.notifySuccess() is called to indicate that the content URL has successfully resolved.

Примечание

  • Если обработчик сохранения зарегистрирован с помощью microsoftTeams.settings.registerOnSaveHandler() , обратный вызов должен вызвать saveEvent.notifySuccess() или saveEvent.notifyFailure() указать результат конфигурации.If a save handler was registered using microsoftTeams.settings.registerOnSaveHandler(), the callback must invoke saveEvent.notifySuccess() or saveEvent.notifyFailure() to indicate the outcome of the configuration.
  • Если обработчик сохранения не зарегистрирован, saveEvent.notifySuccess() вызов автоматически выполняется сразу после нажатия кнопки сохранить .If no save handler was registered, the saveEvent.notifySuccess() call is automatically made immediately upon the user selecting the Save button.

Получение данных контекста для параметров вкладкиGet context data for your tab settings

Для отображения соответствующего контента на вкладке может потребоваться Контекстная информация.Your tab might require contextual information to display relevant content. Контекстные сведения могут улучшить внешний вид вкладки, обеспечивая более настраиваемое взаимодействие с пользователем.Contextual information can further enhance your tab's appeal by providing a more customized user experience.

Интерфейс контекста Teams определяет свойства, которые можно использовать для настройки вкладки.The Teams Context interface defines the properties that can be used for your tab configuration. Вы можете собирать значения переменных контекстных данных двумя способами:You can collect the values of context data variables in two ways:

  1. Вставьте в манифесте заполнители строки запроса URL-адреса configurationURL .Insert URL query string placeholders in your manifest's configurationURL.

  2. Используйте метод Teams SDK microsoftTeams.getContext((context) =>{} .Use the Teams SDK microsoftTeams.getContext((context) =>{} method.

Вставьте заполнители в поле configurationURLInsert placeholders in the configurationURL

Заполнители интерфейса контекста можно добавлять к базе configurationUrl .Context interface placeholders can be added to your base configurationUrl. Например:For example:

Базовый URL-адресBase Url
...
"configurationUrl": "https://yourWebsite/config",
...

Базовый URL-адрес со строками запросаBase URL with query strings

...
"configurationUrl": "https://yourWebsite/config?team={teamId}&channel={channelId}&{locale}"
...

После отправки страницы заполнители строки запроса будут обновлены в Teams с соответствующими значениями.After your page has uploaded, the query string placeholders will be updated by Teams with the relevant values. Вы можете включить логику на странице конфигурации, чтобы извлечь и использовать эти значения.You can include logic in your configuration page to retrieve and use those values. Дополнительные сведения о работе с строками запросов URL-адресов урлсеарчпарамс в веб-документах МДН. Ниже приведен пример того, как извлечь значение из вышеуказанного configurationURL Свойства:For more information on working with URL query strings see URLSearchParams in MDN web docs. Here is an example of how to extract a value from the above configurationURL property:

<script>
   microsoftTeams.initialize();
   const getId = () => {
        let urlParams = new URLSearchParams(document.location.search.substring(1));
        let blueTeamId = urlParams.get('team');
        return blueTeamId
    }
//For testing, you can invoke the following to view the pertinent value:
document.write(getId());
</script>

Использование getContext() функции для получения контекстаUse the getContext() function to retrieve context

При вызове microsoftTeams.getContext((context) => {}) функция получает интерфейс контекста.When invoked, the microsoftTeams.getContext((context) => {}) function retrieves the Context interface. Вы можете добавить эту функцию на страницу конфигурации для получения значений контекста:You can add this function to your configuration page to retrieve context values:

<!-- `userPrincipalName` will render in the span with the id "user". -->

<span id="user"></span>
...
<script>
    microsoftTeams.getContext((context) =>{
        let userId = document.getElementById('user');
        userId.innerHTML = context.userPrincipalName;
    });
</script>
...

Контекст и проверка подлинностиContext and Authentication

Проверка подлинности может потребоваться, прежде чем разрешить пользователю настраивать приложение или контент может включать источники с собственными протоколами проверки подлинности.You might require authentication before allowing a user to configure your app or your content might include sources that have their own authentication protocols. Просмотреть проверку подлинности пользователь в контексте вкладки Microsoft Teams можно использовать для создания URL-адресов страниц проверки подлинности и страниц авторизации.See Authenticate a user in a Microsoft Teams tab Context information can be used to help construct authentication requests and authorization page URLs. Убедитесь, что все домены, используемые на страницах вкладок, указаны в manifest.json validDomains массиве.Make sure that all domains used in your tab pages are listed in the manifest.json validDomains array.

Изменение или удаление вкладкиModify or remove a tab

Поддерживаемые варианты удаления могут дополнительно улучшить взаимодействие с пользователем.Supported removal options can further refine the user experience. Вы можете разрешить пользователям изменять, перенастраивать или переименовывать вкладки группа и канал, устанавливая для свойства манифеста значение canUpdateConfiguration true .You can enable users to modify, reconfigure, or rename a group/channel tab by setting your manifest's canUpdateConfiguration property to true. Кроме того, вы можете указать, что происходит с содержимым при удалении вкладки, включив страницу параметров удаления в свое приложение и задав значение для removeUrl свойства в setSettings() конфигурации (см. ниже).In addition, you can designate what happens to the content when a tab is removed by including a removal options page in your app and setting a value for the removeUrl property in the setSettings() configuration (see below). Личные вкладки нельзя изменить, но можно удалить пользователя.Personal tabs can't be modified but can be uninstalled by the user. Дополнительные сведения можно найти в разделе Создание страницы удаления для вкладки.For more information, see Create a removal page for your tab.

Мобильные приложенияMobile clients

Если вкладка канал и группа отображается в клиентах Teams для мобильных устройств, то setSettings() конфигурация должна иметь значение для websiteUrl Свойства (см. ниже).If you choose to have your channel/group tab appear on Teams mobile clients, the setSettings() configuration must have a value for the websiteUrl property (see below). В ближайшее время будет выпущена полная поддержка вкладок на мобильных клиентах.Full support for tabs on mobile clients will be released soon. Чтобы подготовиться к обновлению, следуйте указаниям для вкладок на странице Mobile при создании вкладок.To prepare for the update, you should follow the guidance for tabs on mobile when creating your tabs.

Настройка Microsoft Teams Сетсеттингс () для страницы удаления и/или мобильных клиентов:Microsoft Teams setSettings() configuration for removal page and/or mobile clients:

microsoftTeams.settings.setSettings({
    contentUrl: "add content page URL here",
    entityId: "add unique name here",
    suggestedDisplayName: "add name to display on tab here",
    websiteUrl: "URL REQUIRED FOR MOBILE CLIENTS",
    removeUrl: "ADD REMOVAL PAGE URL HERE"
});