Учебник: Создание надстройки области задач Excel

  • Статья

С помощью данного учебника вы сможете создать надстройку области задач Excel, которая выполняет следующие действия:

  • Создание таблицы
  • Фильтрация и сортировка таблицы
  • Создание графика
  • Закрепление заголовка таблицы
  • Защита листа
  • Открытие диалогового окна

Совет

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

Если вам нужна полная версия этого руководства, перейдите в репозиторий примеров надстроек Office на сайте GitHub.

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

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

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

yo office

Примечание.

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

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

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

Интерфейс командной строки генератора надстроек Yeoman Office.

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

Примечание.

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

Совет

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

Создание таблицы

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

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

  1. Откройте проект в редакторе кода.

  2. Откройте файл ./src/taskpane/taskpane.html. Этот файл содержит HTML-разметку для панели задач.

  3. Найдите элемент <main> и удалите все строки, которые появляются после открывающего тега <main> и перед закрывающим тегом </main>.

  4. Добавьте указанный ниже текст разметки сразу после открывающего тега <main>.

    <button class="ms-Button" id="create-table">Create Table</button><br/><br/>

  5. Откройте файл ./src/taskpane/taskpane.js. Этот файл содержит код API JavaScript для Office, облегчающий взаимодействие между областью задач и клиентским приложением Office.

  6. Удалите все ссылки на кнопкуrun и функциюrun(), выполнив следующие действия:

    • Найдите и удалите строку document.getElementById("run").onclick = run;.

    • Найдите и удалите всю функцию run().

  7. В вызове функции Office.onReady найдите строку if (info.host === Office.HostType.Excel) { и добавьте следующий код непосредственно после этой строки. Примечание.

    • Этот код добавляет обработчик событий для кнопки create-table .
    • Функция createTable упаковывается в вызов tryCatch (обе функции будут добавлены на следующем шаге). Это позволяет обрабатывать любые ошибки, созданные на уровне JavaScript Office, отдельно от кода службы.
    // Assign event handlers and other initialization logic.
document.getElementById("create-table").onclick = () => tryCatch(createTable);

  8. Добавьте следующие функции в конец файла. Примечание.

    • Бизнес-логика Excel.js будет добавлена в функцию, передаваемую методу Excel.run. Эта логика выполняется не сразу. Вместо этого она добавляется в очередь ожидания команд.

    • Метод context.sync отправляет все команды из очереди в Excel для выполнения.

    • Функция tryCatch будет использоваться всеми функциями, взаимодействующими с книгой из области задач. Перехват ошибок JavaScript в Office таким образом — это удобный способ универсальной обработки любых необъявленных ошибок.

    Примечание.

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

    async function createTable() {
    await Excel.run(async (context) => {

        // TODO1: Queue table creation logic here.

        // TODO2: Queue commands to populate the table with data.

        // TODO3: Queue commands to format the table.

        await context.sync();
    });
}

/** Default helper for invoking an action and handling errors. */
async function tryCatch(callback) {
    try {
        await callback();
    } catch (error) {
        // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
        console.error(error);
    }
}

  9. В функции createTable() замените TODO1 следующим кодом: Примечание.

    • Код создает таблицу с помощью add метода коллекции таблиц листа, которая всегда существует, даже если она пуста. Это стандартный способ создания объектов Excel.js. API конструкторов классов не существуют, а для создания объекта Excel никогда не следует использовать оператор new. Вместо этого следует добавить его к объекту родительской коллекции.

    • Первый параметр метода add— это диапазон, содержащий только первую строку, а не весь диапазон таблицы, который мы в конечном итоге будем использовать. Это связано с тем, что при заполнении строк данных (на следующем этапе) надстройка добавляет к таблице новые строки, а не записывает их в ячейки имеющихся строк. Это распространенный шаблон, так как количество строк в таблице часто неизвестно при ее создании.

    • Имена таблиц должны быть уникальными в рамках всей книги, а не только одного листа.

    const currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
const expensesTable = currentWorksheet.tables.add("A1:D1", true /*hasHeaders*/);
expensesTable.name = "ExpensesTable";

  10. В функции createTable() замените TODO2 следующим кодом. Примечание.

    • значения ячеек диапазона задаются с помощью массива массивов.

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

    expensesTable.getHeaderRowRange().values =
    [["Date", "Merchant", "Category", "Amount"]];

expensesTable.rows.add(null /*add at the end*/, [
    ["1/1/2017", "The Phone Company", "Communications", "120"],
    ["1/2/2017", "Northwind Electric Cars", "Transportation", "142.33"],
    ["1/5/2017", "Best For You Organics Company", "Groceries", "27.9"],
    ["1/10/2017", "Coho Vineyard", "Restaurant", "33"],
    ["1/11/2017", "Bellows College", "Education", "350.1"],
    ["1/15/2017", "Trey Research", "Other", "135"],
    ["1/15/2017", "Best For You Organics Company", "Groceries", "97.88"]
]);

  11. В функции createTable() замените TODO3 следующим кодом: Примечание.

    • код получает ссылку на столбец Сумма, передавая его индекс (с отсчетом от нуля) в метод getItemAt коллекции столбцов таблицы.

      Примечание.

      У объектов коллекций Excel.js (например, TableCollection, WorksheetCollection и TableColumnCollection) есть свойство items, представляющее собой массив дочерних типов объектов (например, Table, Worksheet или TableColumn). Однако сам объект *Collection не является массивом.

    • Затем код форматирует диапазон столбца Сумма как денежные суммы в евро с точностью до второго знака после запятой. Дополнительные сведения о синтаксисе числового формата Excel см. в статье Коды числового формата./

    • Напоследок он обеспечивает достаточные ширину столбцов и высоту строк для размещения самого длинного (или самого высокого) элемента данных. Обратите внимание, что код должен привести объекты Range к нужному формату. У объектов TableColumn и TableRow нет свойств формата.

    expensesTable.columns.getItemAt(3).getRange().numberFormat = [['\u20AC#,##0.00']];
expensesTable.getRange().format.autofitColumns();
expensesTable.getRange().format.autofitRows();

  12. Убедитесь, что вы сохранили все изменения, внесенные в проект.

Тестирование надстройки

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

    Примечание.

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

    Совет

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

    npm run dev-server

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

      npm start

    • Чтобы проверить надстройку в Excel в Интернете, выполните следующую команду в корневом каталоге своего проекта. После выполнения этой команды запустится локальный веб-сервер. Замените "{url}" на URL-адрес документа Excel в 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 в Интернете.

  2. В Excel перейдите на вкладку Главная , а затем нажмите кнопку Показать область задач на ленте, чтобы открыть область задач надстройки.

    Меню

  3. В области задач нажмите кнопку Создать таблицу.

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

Фильтрация и сортировка таблицы

Из этого раздела руководства вы узнаете, как отфильтровать и отсортировать созданную ранее таблицу.

Фильтрация таблицы

  1. Откройте файл ./src/taskpane/taskpane.html.

  2. Найдите элемент <button> для кнопки create-table и после этой строки добавьте следующий текст разметки:

    <button class="ms-Button" id="filter-table">Filter Table</button><br/><br/>

  3. Откройте файл ./src/taskpane/taskpane.js.

  4. В вызове функции Office.onReady найдите строку, назначающую обработчик щелчка для кнопки create-table, и добавьте следующий код после этой строки.

    document.getElementById("filter-table").onclick = () => tryCatch(filterTable);

  5. Добавьте указанную ниже функцию в конец файла.

    async function filterTable() {
    await Excel.run(async (context) => {

        // TODO1: Queue commands to filter out all expense categories except
        //        Groceries and Education.

        await context.sync();
    });
}

  6. В функции filterTable() замените TODO1 следующим кодом: Примечание.

    • Код получает ссылку на столбец, который нужно отфильтровать, передавая имя столбца методу getItem, а не передавая его индекс методу getItemAt, как это делает метод createTable. Так как пользователи могут перемещать столбцы, по заданному индексу может располагаться уже другой столбец. Следовательно, для получения ссылки безопаснее использовать имя столбца. Мы спокойно использовали метод getItemAt в предыдущем разделе, потому что мы использовали его в методе, который создает таблицу, и пользователь никак не мог переместить столбец.

    • Метод applyValuesFilter является одним из нескольких методов фильтрации объекта Filter.

    const currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
const expensesTable = currentWorksheet.tables.getItem('ExpensesTable');
const categoryFilter = expensesTable.columns.getItem('Category').filter;
categoryFilter.applyValuesFilter(['Education', 'Groceries']);

Сортировка таблицы

  1. Откройте файл ./src/taskpane/taskpane.html.

  2. Найдите элемент <button> для кнопки filter-table и после этой строки добавьте следующий текст разметки:

    <button class="ms-Button" id="sort-table">Sort Table</button><br/><br/>

  3. Откройте файл ./src/taskpane/taskpane.js.

  4. В вызове функции Office.onReady найдите строку, назначающую обработчик щелчка для кнопки filter-table, и добавьте следующий код после этой строки.

    document.getElementById("sort-table").onclick = () => tryCatch(sortTable);

  5. Добавьте указанную ниже функцию в конец файла.

    async function sortTable() {
    await Excel.run(async (context) => {

        // TODO1: Queue commands to sort the table by Merchant name.

        await context.sync();
    });
}

  6. В функции sortTable() замените TODO1 следующим кодом: Примечание.

    • Код создает массив объектов SortField, состоящий из одного элемента, так как надстройка сортирует таблицу только по столбцу Merchant.

    • Свойство key объекта SortField — это нулевой индекс столбца, который используется для сортировки таблицы. Строки в таблице сортируются на основе значений в столбце в соотетствующем столбце.

    • Элемент sort объекта Table — это объект TableSort, а не метод. Объекты SortField передаются методу apply объекта TableSort.

    const currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
const expensesTable = currentWorksheet.tables.getItem('ExpensesTable');
const sortFields = [
    {
        key: 1,            // Merchant column
        ascending: false,
    }
];

expensesTable.sort.apply(sortFields);

  7. Убедитесь, что вы сохранили все изменения, внесенные в проект.

Тестирование надстройки

  1. Если локальный веб-сервер уже запущен и ваша надстройка уже загружена в Excel, перейдите к шагу 2. В противном случае запустите локальный веб-сервер и загрузите неопубликованную надстройку:

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

      npm start

    • Чтобы проверить надстройку в Excel в Интернете, выполните следующую команду в корневом каталоге своего проекта. После выполнения этой команды запустится локальный веб-сервер. Замените "{url}" на URL-адрес документа Excel в 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 в Интернете.

  2. Если область задач надстройки еще не открыта в Excel, перейдите на вкладку Главная и нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

  3. Если таблица, ранее добавленная в этом руководстве, отсутствует на открытом листе, нажмите кнопку Создать таблицу в области задач.

  4. Нажмите кнопки Фильтровать таблицу и Сортировать таблицу в любом порядке.

    Excel с кнопками

Создание диаграммы

На этом этапе руководства мы создадим диаграмму, используя данные из ранее созданной таблицы, а затем отформатируем эту диаграмму.

Создание диаграммы с помощью таблицы данных

  1. Откройте файл ./src/taskpane/taskpane.html.

  2. Найдите элемент <button> для кнопки sort-table и после этой строки добавьте следующий текст разметки:

    <button class="ms-Button" id="create-chart">Create Chart</button><br/><br/>

  3. Откройте файл ./src/taskpane/taskpane.js.

  4. В вызове функции Office.onReady найдите строку, назначающую обработчик щелчка для кнопки sort-table, и добавьте следующий код после этой строки.

    document.getElementById("create-chart").onclick = () => tryCatch(createChart);

  5. Добавьте указанную ниже функцию в конец файла.

    async function createChart() {
    await Excel.run(async (context) => {

        // TODO1: Queue commands to get the range of data to be charted.

        // TODO2: Queue command to create the chart and define its type.

        // TODO3: Queue commands to position and format the chart.

        await context.sync();
    });
}

  6. В функции createChart() замените TODO1 следующим кодом. Обратите внимание, что для исключения строки заголовков в коде вместо метода getRange используется метод Table.getDataBodyRange, чтобы получить нужный диапазон данных для диаграммы.

    const currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
const expensesTable = currentWorksheet.tables.getItem('ExpensesTable');
const dataRange = expensesTable.getDataBodyRange();

  7. В функции createChart() замените TODO2 следующим кодом. Обратите внимание на следующие параметры:

    • Первый параметр метода add задает тип диаграммы. Существует несколько десятков типов.

    • Второй параметр задает диапазон данных, включаемых в диаграмму.

    • Третий параметр определяет, как следует отображать на диаграмме ряд точек данных из таблицы: по строкам или по столбцам. Значение auto сообщает Excel, что следует выбрать оптимальный способ.

    const chart = currentWorksheet.charts.add('ColumnClustered', dataRange, 'Auto');

  8. В функции createChart() замените TODO3 следующим кодом. Большая часть этого кода не требует объяснений. Примечание.

    • Параметры метода setPosition задают левую верхнюю и правую нижнюю ячейки области листа, которые должны содержать диаграмму. Excel может настраивать такие параметры, как ширина линий, чтобы диаграмма хорошо выглядела в выделенном для нее пространстве.

    • "Ряд" — это набор точек данных из столбца таблицы. Так как в таблице есть только один нестроковый столбец, Excel делает вывод, что это единственный столбец точек данных для диаграммы. Он рассматривает другие столбцы как метки диаграммы. Следовательно, в диаграмме будет только один ряд, обозначенный индексом 0. К нему следует добавить метку "Значение в €".

    chart.setPosition("A15", "F30");
chart.title.text = "Expenses";
chart.legend.position = "Right";
chart.legend.format.fill.setSolidColor("white");
chart.dataLabels.format.font.size = 15;
chart.dataLabels.format.font.color = "black";
chart.series.getItemAt(0).name = 'Value in \u20AC';

  9. Убедитесь, что вы сохранили все изменения, внесенные в проект.

Тестирование надстройки

  1. Если локальный веб-сервер уже запущен и ваша надстройка уже загружена в Excel, перейдите к шагу 2. В противном случае запустите локальный веб-сервер и загрузите неопубликованную надстройку:

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

      npm start

    • Чтобы проверить надстройку в Excel в Интернете, выполните следующую команду в корневом каталоге своего проекта. После выполнения этой команды запустится локальный веб-сервер. Замените "{url}" на URL-адрес документа Excel в 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 в Интернете.

  2. Если область задач надстройки еще не открыта в Excel, перейдите на вкладку Главная и нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

  3. Если таблица, ранее добавленная в этом руководстве, отсутствует на открытом листе, нажмите кнопку Создать таблицу, а затем кнопки Фильтровать таблицу и Сортировать таблицу в любом порядке.

  4. Нажмите кнопку Create Chart (Создать диаграмму). Будет создана диаграмма, включающая только данные из отфильтрованных строк. Метки точек данных в нижней части диаграммы отсортированы согласно заданному для нее порядку, то есть по именам продавцов в обратном алфавитном порядке.

    Excel с кнопкой

Закрепление заголовка таблицы

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

Закрепление строки заголовков таблицы

  1. Откройте файл ./src/taskpane/taskpane.html.

  2. Найдите элемент <button> для кнопки create-chart и после этой строки добавьте следующий текст разметки:

    <button class="ms-Button" id="freeze-header">Freeze Header</button><br/><br/>

  3. Откройте файл ./src/taskpane/taskpane.js.

  4. В вызове функции Office.onReady найдите строку, назначающую обработчик щелчка для кнопки create-chart, и добавьте следующий код после этой строки.

    document.getElementById("freeze-header").onclick = () => tryCatch(freezeHeader);

  5. Добавьте указанную ниже функцию в конец файла.

    async function freezeHeader() {
    await Excel.run(async (context) => {

        // TODO1: Queue commands to keep the header visible when the user scrolls.

        await context.sync();
    });
}

  6. В функции freezeHeader() замените TODO1 следующим кодом: Примечание.

    • Коллекция Worksheet.freezePanes — это набор закрепленных строк, которые не исчезают с экрана при прокрутке листа.

    • Метод freezeRows принимает в качестве параметра количество строк сверху, которые необходимо закрепить. Мы передаем 1, чтобы закрепить первую строку.

    const currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
currentWorksheet.freezePanes.freezeRows(1);

  7. Убедитесь, что вы сохранили все изменения, внесенные в проект.

Тестирование надстройки

  1. Если локальный веб-сервер уже запущен и ваша надстройка уже загружена в Excel, перейдите к шагу 2. В противном случае запустите локальный веб-сервер и загрузите неопубликованную надстройку:

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

      npm start

    • Чтобы проверить надстройку в Excel в Интернете, выполните следующую команду в корневом каталоге своего проекта. После выполнения этой команды запустится локальный веб-сервер. Замените "{url}" на URL-адрес документа Excel в 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 в Интернете.

  2. Если область задач надстройки еще не открыта в Excel, перейдите на вкладку Главная и нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

  3. Если таблица, ранее добавленная в этом руководстве, присутствует на листе, удалите ее.

  4. В области задач нажмите кнопку Создать таблицу.

  5. Нажмите кнопку Закрепить заголовок.

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

    Лист Excel с замороженным заголовком таблицы.

Защита листа

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

Настройка манифеста для добавления второй кнопки на ленту

  1. Откройте файл манифеста ./manifest.xml.

  2. Найдите элемент Control>.< Этот элемент определяет кнопку Show Taskpane (Показать область задач) на вкладке Главная, которую вы используете для запуска надстройки. Мы добавим вторую кнопку в эту же группу на ленте Главная. Между закрывающим <тегом /Control> и закрывающим <тегом /Group> добавьте следующую разметку.

    <Control xsi:type="Button" id="<!--TODO1: Unique (in manifest) name for button -->">
    <Label resid="<!--TODO2: Button label -->" />
    <Supertip>
        <Title resid="<!-- TODO3: Button tool tip title -->" />
        <Description resid="<!-- TODO4: Button tool tip description -->" />
    </Supertip>
    <Icon>
        <bt:Image size="16" resid="Icon.16x16"/>
        <bt:Image size="32" resid="Icon.32x32"/>
        <bt:Image size="80" resid="Icon.80x80"/>
    </Icon>
    <Action xsi:type="<!-- TODO5: Specify the type of action-->">
        <!-- TODO6: Identify the function.-->
    </Action>
</Control>

  3. В XML-коде, добавленном в файл манифеста, замените TODO1 строкой, которая присваивает кнопке идентификатор, уникальный в пределах этого файла манифеста. Так как кнопка будет включать и выключать защиту листа, укажите "ToggleProtection". После завершения открывающий тег элемента Control должен выглядеть следующим образом:

    <Control xsi:type="Button" id="ToggleProtection">

  4. Следующие три TODOs устанавливают идентификаторы ресурсов или resids. Ресурс должен быть строкой (максимальная длина — 32 символа), и вы создадите эти три строки на следующем этапе. Сейчас вам нужно присвоить идентификаторы ресурсам. Кнопка должна называться "Переключение защиты", но у строки должен быть идентификатор "ProtectionButtonLabel", поэтому элемент Label выглядит следующим образом:

    <Label resid="ProtectionButtonLabel" />

  5. Элемент SuperTip определяет подсказку для кнопки. Заголовок этой подсказки должен совпадать с названием кнопки, поэтому мы используем тот же ИД ресурса — "ProtectionButtonLabel". Описание подсказки будет следующим: "Click to turn protection of the worksheet on and off" (Нажмите для включения или выключения защиты листа). У resid должно быть значение "ProtectionButtonToolTip". Поэтому после завершения элемент SuperTip должен выглядеть следующим образом:

    <Supertip>
    <Title resid="ProtectionButtonLabel" />
    <Description resid="ProtectionButtonToolTip" />
</Supertip>

    Примечание.

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

  6. Для элемента Action в исходном элементе Control, задан тип ShowTaskpane, но новая кнопка будет не открывать область задач, а выполнять специальную функцию, которую вы создадите позже. Поэтому замените TODO5 на ExecuteFunction (тип действия для кнопок, запускающих специальные функции). Открывающий тег элемента Action должен выглядеть следующим образом:

    <Action xsi:type="ExecuteFunction">

  7. У исходного элемента Action есть дочерние элементы, определяющие идентификатор области задач и URL-адрес страницы, которая должна быть открыта в области задач. Но у элемента Action типа ExecuteFunction есть один дочерний элемент, который именует функцию, выполняемую элементом управления. На более позднем этапе вы создадите функцию toggleProtection. Поэтому замените TODO6 следующей разметкой.

    <FunctionName>toggleProtection</FunctionName>

    Теперь весь код Control должен выглядеть вот так:

    <Control xsi:type="Button" id="ToggleProtection">
    <Label resid="ProtectionButtonLabel" />
    <Supertip>
        <Title resid="ProtectionButtonLabel" />
        <Description resid="ProtectionButtonToolTip" />
    </Supertip>
    <Icon>
        <bt:Image size="16" resid="Icon.16x16"/>
        <bt:Image size="32" resid="Icon.32x32"/>
        <bt:Image size="80" resid="Icon.80x80"/>
    </Icon>
    <Action xsi:type="ExecuteFunction">
       <FunctionName>toggleProtection</FunctionName>
    </Action>
</Control>

  8. Прокрутите страницу вниз до раздела Resources манифеста.

  9. Добавьте приведенный ниже код в качестве дочернего элемента bt:ShortStrings.

    <bt:String id="ProtectionButtonLabel" DefaultValue="Toggle Worksheet Protection" />

  10. Добавьте приведенный ниже код в качестве дочернего элемента bt:LongStrings.

    <bt:String id="ProtectionButtonToolTip" DefaultValue="Click to protect or unprotect the current worksheet." />

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

Создание функции защиты листа

  1. Откройте файл .\commands\commands.js.

  2. Добавьте указанную ниже функцию сразу после функции action. Обратите внимание, что мы указываем параметр args для функции, а самая последняя строка функции вызывает args.completed. Это требование для всех команд надстройки типа ExecuteFunction. Это сигнализирует клиентскому приложению Office, что действие функции завершено и пользовательский интерфейс снова может отвечать на запросы.

    async function toggleProtection(args) {
    try {
        await Excel.run(async (context) => {

            // TODO1: Queue commands to reverse the protection status of the current worksheet.

            await context.sync();
        });
    } catch (error) {
        // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
        console.error(error);
    }

    args.completed();
}

  3. Добавьте следующую строку сразу после функции, чтобы зарегистрировать ее.

    Office.actions.associate("toggleProtection", toggleProtection);

  4. В функции toggleProtection замените TODO1 следующим кодом. В этом коде используется свойство защиты объекта листа в стандартном шаблоне переключателя. Объяснение TODO2 будет приведено в следующем разделе.

    const sheet = context.workbook.worksheets.getActiveWorksheet();

// TODO2: Queue command to load the sheet's "protection.protected" property from
//        the document and re-synchronize the document and task pane.

if (sheet.protection.protected) {
    sheet.protection.unprotect();
} else {
    sheet.protection.protect();
}

Добавление кода для получения свойств документа в объекты скрипта области задач

В каждой функции, созданной в этом руководстве до настоящего момента, вы помещаете в очередь команды на запись в документе Office. Каждая функция заканчивалась вызовом метода context.sync(), который отправляет выставленные в очередь команды документу для выполнения. При этом код, который вы добавили на последнем этапе, вызывает свойствоsheet.protection.protected property. В этом заключается существенное отличие от ранее написанных функций, так как sheet является лишь объектом прокси, существующим в скрипте вашей области задач. Объект-прокси не знает о фактическом состоянии защиты документа, поэтому его свойство protection.protected не может иметь реального значения. Чтобы избежать возникновения ошибки, сначала нужно получить сведения о состоянии защиты от документа и задать значение sheet.protection.protected, используя их. Процесс получения делится на три этапа.

  1. Добавление в очередь команды для загрузки (т. е. получения) свойств, которые должен прочесть ваш код.

  2. Вызов метода sync объекта контекста, чтобы можно было отправить документу находящуюся в очереди команду для выполнения, а также для возврата запрошенных данных.

  3. Метод sync асинхронный, поэтому его выполнение должно быть завершено до того, как код вызовет полученные свойства.

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

  1. В функции toggleProtection замените TODO2 следующим кодом: Примечание.

    • У каждого объекта Excel есть метод load. Вы указываете свойства объекта, которые нужно прочесть в параметре как строку имен, разделенных запятыми. В этом случае нужно прочесть подсвойство свойства protection. На подсвойство нужно ссылаться почти так же, как и в остальных частях кода. Отличие заключается в том, что вместо символа "." нужно указать косую черту ("/").

    • Чтобы логика переключения, которая считывает sheet.protection.protected, не срабатывала до выполнения sync и присвоения sheet.protection.protected правильного значения, полученного из документа, она должна использоваться после того, как оператор await обеспечит выполнение sync.

    sheet.load('protection/protected');
await context.sync();

    Когда все будет готово, функция должна выглядеть так:

    async function toggleProtection(args) {
    try {
        await Excel.run(async (context) => {
            const sheet = context.workbook.worksheets.getActiveWorksheet();

            sheet.load('protection/protected');
            await context.sync();

            if (sheet.protection.protected) {
                sheet.protection.unprotect();
            } else {
                sheet.protection.protect();
            }

            await context.sync();
        });
    } catch (error) {
        // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
        console.error(error);
    }

    args.completed();
}

  2. Убедитесь, что вы сохранили все изменения, внесенные в проект.

Тестирование надстройки

  1. Закройте все приложения Office, включая Excel (или закройте вкладку браузера, если вы используете Excel в Интернете).

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

  3. Если локальный веб-сервер уже запущен, остановите его, введя следующую команду в командной строке. Это должно закрыть командное окно узла.

    npm stop

  4. Так как файл манифеста был обновлен, требуется повторно загрузить неопубликованную надстройку, используя обновленный файл манифеста. Запустите локальный веб-сервер и загрузите неопубликованную надстройку.

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

      npm start

    • Чтобы проверить надстройку в Excel в Интернете, выполните следующую команду в корневом каталоге своего проекта. После выполнения этой команды запустится локальный веб-сервер. Замените "{url}" на URL-адрес документа Excel в 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 в Интернете.

  5. На вкладке Главная в Excel нажмите кнопку Переключение защиты листа. Обратите внимание, что большинство элементов управления на ленте отключены (серые), как показано на следующем снимке экрана.

    Лента Excel с выделенной и включенной кнопкой

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

  7. Нажмите кнопку Переключение защиты листа еще раз, и элементы управления включатся, после чего вы сможете изменить значения ячеек.

Открытие диалогового окна

На данном заключительном этапе, указанном в руководстве, вы откроете диалоговое окно в своей надстройке, передадите сообщение из процесса диалогового окна в процесс области задач и закроете диалоговое окно. Диалоговые окна надстройки Office являются немодальными: пользователь может продолжать взаимодействовать как с документом в приложении Office, так и с главной страницей в области задач.

Создание страницы диалогового окна

  1. В папке ./src, расположенной в корне проекта, создайте папку с именем dialogs.

  2. В папке ./src/dialogs создайте файл с именем popup.html.

  3. Добавьте в файл popup.html приведенный ниже код. Примечание:

    • На странице есть поле<input>, где пользователь будет вводить свое имя, и кнопка, при нажатии которой это имя будет отправлено в панель задач, где оно будет отображаться.

    • Код загружает скрипт под названием popup.js, который будет создан на более позднем этапе.

    • Он также загружает библиотеку Office.js, так как она будет использоваться в popup.js.

    <!DOCTYPE html>
<html>
    <head lang="en">
        <title>Dialog for My Office Add-in</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <!-- For more information on Fluent UI, visit https://developer.microsoft.com/fluentui. -->
        <link rel="stylesheet" href="https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/9.6.1/css/fabric.min.css"/>

        <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
        <script type="text/javascript" src="popup.js"></script>

    </head>
    <body style="display:flex;flex-direction:column;align-items:center;justify-content:center">
        <p class="ms-font-xl">ENTER YOUR NAME</p>
        <input id="name-box" type="text"/><br/><br/>
        <button id="ok-button" class="ms-Button">OK</button>
    </body>
</html>

  4. В папке ./src/dialogs создайте файл с именем popup.js.

  5. Добавьте указанный ниже код в файл popup.js. Обратите внимание на указанные ниже аспекты этого кода.

    • Каждая страница, вызывающая API в библиотеке Office.js, должна сначала убедиться, что библиотека полностью инициализирована. Лучший способ сделать это — вызвать функцию Office.onReady(). Вызов метода Office.onReady() должен выполняться до каких-либо вызовов Office.js, поэтому назначение указано в файле скрипта, загружаемом страницей, как в этом случае.
    Office.onReady((info) => {
    // TODO1: Assign handler to the OK button.
});

// TODO2: Create the OK button handler.

  6. Замените TODO1 на приведенный ниже код. Вы создадите функцию sendStringToParentPage на следующем этапе.

    document.getElementById("ok-button").onclick = () => tryCatch(sendStringToParentPage);

  7. Замените TODO2 приведенным ниже кодом. Метод messageParent передает свой параметр родительской странице (в данном случае это страница на панели задач). Параметр должен быть строковым. Это подразумевает все, что можно сериализовать в виде строки (например, XML или JSON), или любой тип, который можно представить в виде строки. При этом также добавляется тот же tryCatch метод , который используется вtaskpane.jsдля обработки ошибок.

    function sendStringToParentPage() {
    const userName = document.getElementById("name-box").value;
    Office.context.ui.messageParent(userName);
}

/** Default helper for invoking an action and handling errors. */
async function tryCatch(callback) {
    try {
        await callback();
    } catch (error) {
        // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
        console.error(error);
    }
}

Примечание.

Файл popup.html и загружаемый по ссылке в нем файл popup.js выполняются в полностью отдельной среде выполнения браузера из области задач надстройки. Если файл popup.js был передан в тот же файл bundle.js, что и файл app.js, надстройка загрузит два экземпляра файла bundle.js, что противоречит цели объединения. Поэтому эта надстройка вообще не передает файл popup.js.

Обновление настроек конфигурации webpack

Откройте файл webpack.config.js в корневом каталоге проекта и выполните описанные ниже шаги.

  1. Найдите объект entry в объекте config и добавьте новую запись для popup.

    popup: "./src/dialogs/popup.js"

    После этого новый объект entry будет выглядеть следующим образом:

    entry: {
  polyfill: "@babel/polyfill",
  taskpane: "./src/taskpane/taskpane.js",
  commands: "./src/commands/commands.js",
  popup: "./src/dialogs/popup.js"
},

  2. Найдите массив plugins в объекте config и добавьте следующий объект в конец массива.

    new HtmlWebpackPlugin({
  filename: "popup.html",
  template: "./src/dialogs/popup.html",
  chunks: ["polyfill", "popup"]
})

    После этого новый массив plugins будет выглядеть следующим образом:

    plugins: [
  new CleanWebpackPlugin(),
  new HtmlWebpackPlugin({
    filename: "taskpane.html",
    template: "./src/taskpane/taskpane.html",
    chunks: ['polyfill', 'taskpane']
  }),
  new CopyWebpackPlugin([
  {
    to: "taskpane.css",
    from: "./src/taskpane/taskpane.css"
  }
  ]),
  new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"]
  }),
  new HtmlWebpackPlugin({
    filename: "popup.html",
    template: "./src/dialogs/popup.html",
    chunks: ["polyfill", "popup"]
  })
],

  3. Если локальный веб-сервер запущен, остановите его, введя следующую команду в командной строке. Это должно закрыть командное окно узла.

    npm stop

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

    npm run build

Открытие диалогового окна из области задач

  1. Откройте файл ./src/taskpane/taskpane.html.

  2. Найдите элемент <button> для кнопки freeze-header и после этой строки добавьте следующий текст разметки:

    <button class="ms-Button" id="open-dialog">Open Dialog</button><br/><br/>

  3. В диалоговом окне пользователю будет предложено ввести имя и передать имя пользователя в область задач. Область задач отобразит его в подписи. Непосредственно после только что добавленного элемента button добавьте приведенный ниже текст разметки.

    <label id="user-name"></label><br/><br/>

  4. Откройте файл ./src/taskpane/taskpane.js.

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

    document.getElementById("open-dialog").onclick = openDialog;

  6. Добавьте следующее объявление в конец файла. Эта переменная удерживает объект в контексте выполнения родительской страницы, который служит посредником для контекста выполнения страницы диалогового окна.

    let dialog = null;

  7. Добавьте следующую функцию в конец файла (после объявления dialog). Важно отметить, что в этом коде отсутствует вызов Excel.run. Это связано с тем, что API, открывающий диалоговое окно, совместно используется всеми приложениями Office, поэтому относится к общему API JavaScript для Office, а не API для Excel.

    function openDialog() {
    // TODO1: Call the Office Common API that opens a dialog.
}

  8. Замените TODO1 приведенным ниже кодом. Примечание.

    • Метод displayDialogAsync открывает диалоговое окно в центре экрана.

    • Первый параметр — это URL-адрес открываемой страницы.

    • Второй параметр передает параметры. height и width— процентные значения размера окна для приложения Office.

    Office.context.ui.displayDialogAsync(
    'https://localhost:3000/popup.html',
    {height: 45, width: 55},

    // TODO2: Add callback parameter.
);

Обработка сообщения из диалогового окна и закрытие диалогового окна

  1. В функции openDialog в файле ./src/taskpane/taskpane.js замените TODO2 следующим кодом. Примечание.

    • Обратный вызов выполняется сразу же после успешного открытия диалогового окна и до того, как пользователь предпримет какие-либо действия в диалоговом окне.

    • result.value — это объект, который выступает в качестве посредника между контекстами выполнения родительских страниц и страниц диалоговых окон.

    • Функция processMessage будет создана на более позднем этапе. Этот обработчик будет обрабатывать любые значения, которые отправляются со страницы диалогового окна с вызовами функции messageParent.

    function (result) {
    dialog = result.value;
    dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
}

  2. Добавьте указанную ниже функцию после функции openDialog.

    function processMessage(arg) {
    document.getElementById("user-name").innerHTML = arg.message;
    dialog.close();
}

  3. Убедитесь, что вы сохранили все изменения, внесенные в проект.

Тестирование надстройки

  1. Если локальный веб-сервер уже запущен и ваша надстройка уже загружена в Excel, перейдите к шагу 2. В противном случае запустите локальный веб-сервер и загрузите неопубликованную надстройку:

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

      npm start

    • Чтобы проверить надстройку в Excel в Интернете, выполните следующую команду в корневом каталоге своего проекта. После выполнения этой команды запустится локальный веб-сервер. Замените "{url}" на URL-адрес документа Excel в 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 в Интернете.

  2. Если область задач надстройки еще не открыта в Excel, перейдите на вкладку Главная и нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

  3. Нажмите кнопку Open Dialog (Открыть диалоговое окно) в области задач.

  4. Когда диалоговое окно открыто, перетащите его и измените его размер. Обратите внимание, что вы можете взаимодействовать с листом и нажимать другие кнопки в области задач, но вы не можете запустить второе диалоговое окно на одной и той же странице панели задач.

  5. В диалоговом окне введите имя и нажмите кнопку OK. В области задач отобразится имя, и диалоговое окно закроется.

  6. При необходимости в файле ./src/taskpane/taskpane.js закомментируйте строку dialog.close(); в processMessage функции. Повторите шаги этого раздела. Диалоговое окно остается открытым, и вы можете изменить имя. Можно закрыть его вручную, нажав кнопку X в правом верхнему углу.

    Excel с кнопкой Открыть диалоговое окно в области задач надстройки и диалоговым окном, отображаемым на листе.

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

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

Общие сведения о надстройках Excel

Примеры кода

См. также