Создание надстройки Office с базовым интерфейсом первого запуска

Статья
09/06/2024

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

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

Совет

Если вы хотите получить полную версию этого руководства, посетите репозиторий примеров надстроек Office на сайте GitHub.

Предварительные условия

Выберите краткое руководство yo Office для приложения Office, которое вы хотите использовать.
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
Следуйте инструкциям в выбранном кратком руководстве. После завершения работы с разделом "Попробовать" вернитесь сюда, чтобы продолжить.

Реализация интерфейса первого запуска

Обновление HTML-файла

Четко прояснять область пользовательского интерфейса, которая будет частью интерфейса первого запуска. В этом руководстве вы создадите <div> элемент с id именем first-run-experience, который представляет то, что пользователи видят только при первом запуске надстройки.

Откройте taskpane.html. Замените <main> элемент следующей разметкой, а затем сохраните файл. Некоторые заметки об этой разметке:

Элемент first-run-experience <div> вставляется в <main> элемент . Он содержит список функций надстроек Office. По умолчанию этот <div> параметр не отображается.
Первый <p> элемент предоставляет пользователю инструкции по использованию надстройки.

<main id="app-body" class="ms-welcome__main" style="display: none;">
    <div id="first-run-experience" style="display: none;">
        <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
        <ul class="ms-List ms-welcome__features">
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Ribbon ms-font-xl"></i>
                <span class="ms-font-m">Achieve more with Office integration</span>
            </li>
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Unlock ms-font-xl"></i>
                <span class="ms-font-m">Unlock features and functionality</span>
            </li>
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Design ms-font-xl"></i>
                <span class="ms-font-m">Create and visualize like a pro</span>
            </li>
        </ul>
    </div>
    <p class="ms-font-l">Select any range of cells in the worksheet, then click <b>Run</b>.</p>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Run</span>
    </div>
    <p><label id="item-subject"></label></p>    
</main>

Если вы выбрали приложение Office помимо Excel, обновите первый <p> элемент более подходящими инструкциями.

Обновление файла JavaScript

Обновите файл JavaScript, чтобы отобразить интерфейс первого запуска, если пользователь впервые запускает надстройку.

Откройте файл taskpane.js. Замените инструкцию Office.onReady приведенным ниже кодом, а затем сохраните файл. Некоторые заметки об этом коде:
- Он проверяет локальное хранилище на наличие ключа с именем "showedFRE". Если ключ не существует, покажите интерфейс первого запуска.
- Она добавляет новую функцию с именем showFirstRunExperience , которая отображает интерфейс первого запуска, <div> добавленный в HTML. Эта функция также добавляет элемент "showedFRE" в локальное хранилище.
```
Office.onReady((info) => {
  if (info.host === Office.HostType.Excel) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";

    // showedFRE is created and set to "true" when you call showFirstRunExperience().
    if (!localStorage.getItem("showedFRE")) {
      showFirstRunExperience();
    }

    document.getElementById("run").onclick = run;
  }
});

async function showFirstRunExperience() {
  document.getElementById("first-run-experience").style.display = "flex";
  localStorage.setItem("showedFRE", true);
}  
```
Если вы выбрали приложение Office помимо Excel, обновите условие первой if инструкции, чтобы проверка для выбранного типа Office.HostType.

Обновление CSS-файла

Обновите CSS-файл <div>, чтобы убедиться, что пользовательский интерфейс надстройки имеет соответствующий стиль с учетом добавления интерфейса первого запуска.

Откройте файл taskpane.css . Замените строку .ms-welcome__main { приведенным ниже кодом, а затем сохраните файл.
```
.ms-welcome__main, .ms-welcome__main > div {
```

Проверка

Убедитесь, что веб-сервер запущен и надстройка загружена неопубликованно, а затем откройте область задач. Дополнительные сведения см. в инструкции в кратком руководстве, которое вы использовали.
Убедитесь, что область задач содержит список функций.
Закройте область задач и снова откройте ее. Убедитесь, что в области задач больше не отображается список компонентов.

Дальнейшие действия

Поздравляем, вы успешно создали надстройку области задач Office с интерфейсом первого запуска!

Подготовка рабочей среды

В этом руководстве вы реализовали базовый интерфейс первого запуска. Чтобы интерфейс первого запуска был готов для пользователей, следует учесть следующее:

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

Если вы планируете сделать надстройку доступной в AppSource Marketplace, вам потребуется надежный и полезный интерфейс первого запуска. Дополнительные сведения см. в статье Рекомендации по разработке надстроек Office.

Примеры кода

Руководство по завершению работы с первым запуском. Результат работы с этим руководством в Excel.

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