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

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

Примечание.

Интерфейс первого запуска рекомендуется использовать для надстроек Office. Это помогает пользователям понять функции надстройки и повышает вовлеченность.

Что вы узнаете

Добавление пользовательского интерфейса первого запуска в надстройку.
Использование локального хранилища браузера для сохранения пользовательского состояния.
Обновление файлов HTML, TypeScript или JavaScript и CSS надстройки для поддержки интерфейса первого запуска.

Обзор

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

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

Действия

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

Обновите HTML: добавьте контейнер для интерфейса первого запуска.
Обновите TypeScript или JavaScript: проверьте локальное хранилище и при необходимости отобразите пользовательский интерфейс первого запуска.
Обновите CSS. Убедитесь, что новый пользовательский интерфейс имеет одинаковый стиль.
Протестируйте надстройку. Убедитесь, что интерфейс первого запуска работает должным образом.

Итак, приступим!

Совет

Если вы хотите получить полную версию этого руководства, посетите репозиторий примеров надстроек 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> элемент более подходящими инструкциями.

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

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

Если вы выбрали Excel, PowerPoint или Word с унифицированным манифестом для Microsoft 365, прежде чем продолжить, выполните следующие действия. В противном случае перейдите к следующему шагу.
1. Откройте соответствующий файл имени приложения.ts в папке ./src/taskpane. Например, если вы использовали Excel, это ./src/taskpane/excel.ts.
2. Переименуйте функцию приложения (например, runExcel, runPowerPointили runWord) в run.
3. Скопируйте все содержимое этого файла, а затем замените все содержимое taskpane.ts.
4. Удалите файл имени приложения.ts (например, excel.ts).
Откройте файл taskpane.ts или 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;
  }
});

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 с интерфейсом первого запуска!

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

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

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

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

Примеры кода

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

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-11