Создание первой надстройки области задач Word

В этой статье вы ознакомитесь с процессом создания надстройки для области задач Word.

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

Надстройку Office можно создать с помощью генератора Yeoman для надстроек Office или Visual Studio. Генератор Yeoman создает проект Node.js, которым можно управлять с помощью Visual Studio Code или любого другого редактора, а Visual Studio создает решение Visual Studio. Выберите вкладку с нужным вариантом и следуйте инструкциям, чтобы создать надстройку и протестировать ее локально.

Генератор Yeoman

Необходимые компоненты

• Node.js (последняя версия LTS). Посетите сайтNode.js , чтобы скачать и установить правильную версию для вашей операционной системы.

• Последняя версия Yeoman и генератора Yeoman для надстроек Office. Выполните в командной строке указанную ниже команду, чтобы установить эти инструменты глобально.

  npm install -g yo generator-office
  

  Примечание.

  Даже если вы уже установили генератор Yeoman, рекомендуем обновить пакет до последней версии из npm.

• Пакет Office, подключенный к подписке Microsoft 365 (включая Office в Интернете).

  Примечание.

  Если у вас еще нет Office, вы можете получить подписку разработчика на Microsoft 365 E5 в рамках программы microsoft 365 для разработчиков. Дополнительные сведения см. в разделе Часто задаваемые вопросы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

Создание проекта надстройки

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

yo office

Примечание.

При выполнении команды yo office может появиться запрос о политиках сбора данных генератора Yeoman и средств CLI надстройки Office. Используйте предоставленные сведения, чтобы ответить на запросы подходящим образом.

При появлении запроса предоставьте следующую информацию для создания проекта надстройки.

• Выберите тип проекта:Office Add-in Task Pane project
• Выберите тип скрипта:JavaScript
• Как вы хотите назвать надстройку?My Office Add-in
• Какое клиентское приложение Office вы хотите поддерживать?Word

После завершения работы мастера генератор создаст проект и установит вспомогательные компоненты Node.

Примечание.

Если вы используете Node.js версии 20.0.0 или более поздней, при запуске установки генератора может появилось предупреждение о том, что у вас неподдерживаемый модуль. Мы работаем над исправлением этого. В то же время предупреждение не влияет на генератор или проект, который вы создаете, поэтому его можно игнорировать.

Совет

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

Знакомство с проектом

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

• Файл ./manifest.xml в корневом каталоге проекта определяет настройки и возможности надстройки.
• Файл ./src/taskpane/taskpane.html содержит разметку HTML для области задач.
• Файл ./src/taskpane/taskpane.css содержит код CSS, который применяется к содержимому области задач.
• Файл ./src/taskpane/taskpane.js содержит код API JavaScript для Office, который упрощает взаимодействие между областью задач и клиентским приложением Office.

Проверка

1. Перейдите к корневой папке проекта.

   cd "My Office Add-in"
   

2. Выполните указанные ниже действия, чтобы запустить локальный веб-сервер и загрузить неопубликованную надстройку.

   Примечание.

   Надстройки Office должны использовать HTTPS, а не HTTP, даже во время разработки. Если после выполнения одной из следующих команд вам будет предложено установить сертификат, примите запрос на установку сертификата, который предоставляет генератор Yeoman. Кроме того, вам может потребоваться запустить командную строку или терминал с правами администратора, чтобы внести изменения.

   Совет

   Если вы тестируете надстройку на компьютере Mac, перед продолжением выполните указанную ниже команду. После выполнения этой команды запустится локальный веб-сервер.

   npm run dev-server
   

   • Чтобы проверить надстройку в Word, выполните приведенную ниже команду в корневом каталоге своего проекта. При этом запускается локальный веб-сервер (если он еще не запущен) и открывается приложение Word с загруженной надстройкой.

     npm start
     

   • Чтобы проверить надстройку в Word в браузере, выполните приведенную ниже команду в корневом каталоге проекта. После выполнения этой команды запустится локальный веб-сервер. Замените "{url}" на URL-адрес документа Word в OneDrive или библиотеке SharePoint, для которой у вас есть разрешения.

     Примечание.

     Если вы разрабатываете на компьютере Mac, заключите в одинарные {url} кавычки. Не делайте этого в Windows.

     npm run start:web -- --document {url}
     

     Ниже приведены примеры.

     • npm run start:web -- --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
     • npm run start:web -- --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
     • npm run start:web -- --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

     Если надстройка не загружает неопубликованное приложение в документе, вручную загрузите ее, следуя инструкциям в разделе Ручная загрузка неопубликованных надстроек для Office в Интернете.

3. В Word, если область задач "Моя надстройка Office" еще не открыта, откройте новый документ, перейдите на вкладку Главная, а затем нажмите кнопку Показать область задач на ленте, чтобы открыть область задач надстройки.

   

4. В нижней части области задач выберите ссылку Выполнить, чтобы добавить текст "Hello World" синего цвета в документ.

   

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

Поздравляем! Вы успешно создали надстройку области задач Word! Чтобы узнать больше о возможностях надстроек Word и создать более сложную надстройку, воспользуйтесь руководством по надстройкам Word.

Руководство по надстройкам Word

Visual Studio

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

• Visual Studio 2019 или более поздней версии с установленной рабочей нагрузкой Разработка надстроек для Office и SharePoint.

  Примечание.

  Если вы уже установили Visual Studio, используйте установщик Visual Studio, чтобы убедиться, что также установлена рабочая нагрузка Разработка надстроек для Office и SharePoint.

• Пакет Office, подключенный к подписке Microsoft 365 (включая Office в Интернете).

Создание проекта надстройки

1. В Visual Studio выберите пункт Создать проект.

2. Используя поле поиска, введите надстройка. Выберите вариант Веб-надстройка Word и нажмите кнопку Далее.

3. Присвойте проекту имя и нажмите кнопку Создать.

4. Visual Studio создаст решение, и два соответствующих проекта появятся в обозревателе решений. В Visual Studio откроется файл Home.html.

Обзор решения Visual Studio

После завершения работы мастера Visual Studio создает решение, которое содержит два проекта.

Проект	Описание
Проект надстройки	Содержит только XML-файл манифеста со всеми параметрами надстройки. Эти параметры помогают приложению Office определить условия активации и место отображения надстройки. Visual Studio создает этот файл автоматически, чтобы вы могли сразу запускать проект и использовать надстройку. Измените эти параметры в любое время, изменив XML-файл.
Проект веб-приложения	Содержит страницы контента надстройки, включающие все файлы и ссылки на файлы, необходимые для разработки страниц HTML и JavaScript с поддержкой Office. При разработке надстройки Visual Studio размещает веб-приложение на локальном сервере IIS. Для публикации надстройки этот проект веб-приложения нужно развернуть на веб-сервере.

Обновление кода

1. Файл Home.html содержит HTML-контент, который будет отображаться в области задач надстройки. В файле Home.html замените элемент <body> на приведенную ниже часть кода и сохраните файл.

   <body>
       <div id="content-header">
           <div class="padding">
               <h1>Welcome</h1>
           </div>
       </div>
       <div id="content-main">
           <div class="padding">
               <p>Choose the buttons below to add boilerplate text to the document by using the Word JavaScript API.</p>
               <br />
               <h3>Try it out</h3>
               <button id="emerson">Add quote from Ralph Waldo Emerson</button>
               <br /><br />
               <button id="checkhov">Add quote from Anton Chekhov</button>
               <br /><br />
               <button id="proverb">Add Chinese proverb</button>
           </div>
       </div>
       <br />
       <div id="supportedVersion"/>
   </body>
   

2. Откройте файл Home.js в корневой папке проекта веб-приложения. Этот файл содержит скрипт надстройки. Замените все его содержимое указанным ниже кодом и сохраните файл.

   'use strict';
   
   (function () {
   
       Office.onReady(function() {
           // Office is ready.
           $(document).ready(function () {
               // The document is ready.
               // Use this to check whether the API is supported in the Word client.
               if (Office.context.requirements.isSetSupported('WordApi', '1.1')) {
                   // Do something that is only available via the new APIs.
                   $('#emerson').on("click", insertEmersonQuoteAtSelection);
                   $('#checkhov').on("click", insertChekhovQuoteAtTheBeginning);
                   $('#proverb').on("click", insertChineseProverbAtTheEnd);
                   $('#supportedVersion').html('This code is using Word 2016 or later.');
               } else {
                   // Lets you know that this code will not work with your version of Word.
                   $('#supportedVersion').html('This code requires Word 2016 or later.');
               }
           });
       });
   
       async function insertEmersonQuoteAtSelection() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document.
               const thisDocument = context.document;
   
               // Queue a command to get the current selection.
               // Create a proxy range object for the selection.
               const range = thisDocument.getSelection();
   
               // Queue a command to replace the selected text.
               range.insertText('"Hitch your wagon to a star." - Ralph Waldo Emerson\n', Word.InsertLocation.replace);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from Ralph Waldo Emerson.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   
       async function insertChekhovQuoteAtTheBeginning() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document body.
               const body = context.document.body;
   
               // Queue a command to insert text at the start of the document body.
               body.insertText('"Knowledge is of no value unless you put it into practice." - Anton Chekhov\n', Word.InsertLocation.start);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from Anton Chekhov.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   
       async function insertChineseProverbAtTheEnd() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document body.
               const body = context.document.body;
   
               // Queue a command to insert text at the end of the document body.
               body.insertText('"To know the road ahead, ask those coming back." - Chinese proverb\n', Word.InsertLocation.end);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from a Chinese proverb.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   })();
   

3. Откройте файл Home.css в корневой папке проекта веб-приложения. Этот файл определяет специальные стили надстройки. Замените все его содержимое указанным ниже кодом и сохраните файл.

   #content-header {
       background: #2a8dd4;
       color: #fff;
       position: absolute;
       top: 0;
       left: 0;
       width: 100%;
       height: 80px;
       overflow: hidden;
   }
   
   #content-main {
       background: #fff;
       position: fixed;
       top: 80px;
       left: 0;
       right: 0;
       bottom: 0;
       overflow: auto;
   }
   
   .padding {
       padding: 15px;
   }
   

Обновление манифеста

1. Откройте XML-файл манифеста в проекте надстройки. Этот файл определяет параметры и возможности надстройки.

2. Элемент ProviderName содержит заполнитель. Замените его на свое имя.

3. Атрибут DefaultValue элемента DisplayName содержит заполнитель. Замените его на строку Моя надстройка Office.

4. Атрибут DefaultValue элемента Description содержит заполнитель. Замените его строкой Надстройка области задач для Word.

5. Сохраните файл.

   ...
   <ProviderName>John Doe</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <!-- The display name of your add-in. Used on the Store and various places of the Office UI such as the add-in's dialog. -->
   <DisplayName DefaultValue="My Office Add-in" />
   <Description DefaultValue="A task pane add-in for Word."/>
   ...
   

Проверка

1. В Visual Studio протестируйте только что созданную надстройку Word, нажав клавишу F5 или выбрав Отладка>Начать отладку, чтобы запустить Word с кнопкой Показать область задач на ленте. Надстройка будет размещена на локальном сервере IIS.

2. В Word, если область задач надстройки еще не открыта, выберите вкладку Главная, а затем нажмите кнопку Показать область задач на ленте, чтобы открыть область задач надстройки. (Если вы используете корпоративную бессрочную версию Office 2016 или более раннюю версию, настраиваемые кнопки не поддерживаются. Вместо этого область задач откроется немедленно.)

   

3. В области задач нажмите любую кнопку, чтобы добавить стандартный текст в документ.

   

Примечание.

Чтобы увидеть выходные данныеconsole.log, нужен отдельный набор средств разработчика для консоли JavaScript. Дополнительные сведения о средствах F12 и средствах разработчика Microsoft Edge см. в статье Отладка надстроек с помощью средств разработчика для Internet Explorer, Отладка надстроек с помощью средств разработчика для устаревшей версии Microsoft Edge или Отладка надстроек с помощью средств разработчика в Microsoft Edge (на основе Chromium).

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

Поздравляем! Вы успешно создали надстройку области задач Word! Далее, чтобы узнать больше о разработке надстроек Office с помощью Visual Studio, перейдите к следующей статье.

Разработка надстроек Office с помощью Visual Studio

Устранение неполадок

• Убедитесь, что ваша среда готова к разработке в Office, следуя инструкциям в разделе Настройка среды разработки.

• Автоматическое npm install выполнение шага Yo Office может завершиться ошибкой. Если при попытке запустить npm startвы видите ошибки , перейдите в только что созданную папку проекта в командной строке и вручную запустите npm install. Дополнительные сведения о Yo Office см. в статье Создание проектов надстроек Office с помощью генератора Yeoman.

• Если надстройка отображает ошибку (например, "Не удалось запустить эту надстройку. Закройте это диалоговое окно, чтобы игнорировать проблему, или нажмите кнопку "Перезапустить", чтобы повторить попытку.") При нажатии клавиши F5 или нажатии кнопки Отладка>Начать отладку в Visual Studio см . раздел Отладка надстроек Office в Visual Studio для других параметров отладки.

• В некоторых примерах кода используется ES6 JavaScript. Это несовместимо с более старыми версиями Office, которые используют подсистему браузера Trident (Интернет-Обозреватель 11). Сведения о поддержке этих платформ в надстройке см. в разделе Поддержка более старых веб-представлений Майкрософт и версий Office. Если у вас еще нет подписки Microsoft 365 для разработки, вы можете получить право на Microsoft 365 E5 подписку разработчика в рамках программы microsoft 365 для разработчиков. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

Примеры кода

• Word надстройка "мир Hello". Узнайте, как создать простую надстройку Office с манифестом, веб-страницей HTML и логотипом.

См. также

• Обзор платформы надстроек Office
• Разработка надстроек Office
• Обзор надстроек Word
• Примеры кода надстроек Word
• Справочник по API JavaScript для Word
• Использование Visual Studio Code для публикации