Краткое руководство. Создание первой надстройки области задач Word с помощью Visual Studio

В этом кратком руководстве вы создадите надстройку области задач Word, которая демонстрирует, как:

  • Вставка текста в разных местах документа (выделение, начало, конец).
  • Используйте API JavaScript Word для управления содержимым документа.
  • Настройка проекта Visual Studio для разработки надстроек Office.

Что вы будете создавать

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

Ключевые функции, которые вы будете реализовывать

  • Вставка содержимого в текущий выделенный фрагмент.
  • Вставьте содержимое в начало документа.
  • Вставьте содержимое в конец документа.
  • Обработка асинхронных операций с помощью API JavaScript Word.

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

  • 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 создает решение, которое содержит два проекта.

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

Шаг 1. Обновление разметки HTML

Файл 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. Добавление функций JavaScript

Откройте файл 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;
}

Шаг 4. Обновление манифеста надстройки

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

  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, если область задач надстройки еще не открыта, выберите вкладку Главная, а затем нажмите кнопку Показать область задач на ленте, чтобы открыть область задач надстройки.

    Приложение Word с выделенной кнопкой Показать область задач.

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

    Приложение Word с загруженной стандартной надстройкой.

Примечание.

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

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

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

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

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

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

Примеры кода

См. также

Основные понятия

Справочник по API и инструменты

Публикация и развертывание

  • Last updated on