Введение в Office.js и надстройки Excel

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

Зачем нужен Office.js?

Office.js — это JavaScript API от Microsoft, который позволяет разработчикам взаимодействовать с приложениями Office, включая Excel. Он предоставляет широкий набор инструментов для доступа к объектам Excel, таким как рабочие листы, диапазоны, таблицы и диаграммы, и управления ими. Это API особенно полезно, поскольку оно работает на различных платформах, включая веб-версии Excel для Windows и Mac.

Настройка среды разработки

Перед началом кодирования необходимо настроить среду разработки. Вот предварительные условия:

  • Установите Node.js: скачайте последнюю версию LTS с сайта Node.js.
  • Установка Yeoman и генератора Yeoman для надстроек Office: используйте команду npm install -g yo generator-office.
  • Создайте проект надстройки: запустите команду yo office в терминале. Далее следуйте инструкциям для выбора типа проекта, типа скрипта и имени надстройки. Пример запросов может выглядеть так:
    • Выберите тип проекта: Project Office Add-in Task Pane.
    • Выберите тип скрипта: Javascript.
    • Как будет называться ваша надстройка? Моя надстройка Excel.
    • Приложение Office, для которого вы хотите создать поддержку? Excel. После завершения работы мастера генератор создаст проект и установит необходимые компоненты Node.

Понимание API Office.js

API Office.js включает два основных JavaScript объектных модели: Excel JavaScript API и Common API.

Excel JavaScript API Введённый с Office 2016, Excel JavaScript API предоставляет строго типизированные объекты для взаимодействия с элементами Excel, такими как рабочие листы, диапазоны, таблицы, диаграммы и многое другое. Примером использования этого API для записи данных на рабочий лист является:

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let headers = [["Продукт", "Количество", "Цена за единицу", "Итого"]];
    let headerRange = sheet.getRange("B2:E2");
    headerRange.values = headers;
    headerRange.format.fill.color = "#4472C4";
    headerRange.format.font.color = "white";

    let productData = [
        ["Миндаль", 6, 7.5],
        ["Кофе", 20, 34.5],
        ["Шоколад", 10, 9.56],
    ];
    let dataRange = sheet.getRange("B3:D5");
    dataRange.values = productData;

    await context.sync();
});

Common API Представленный с Office 2013, Common API обеспечивает доступ к функциям, общим для нескольких приложений Office, таких как элементы пользовательского интерфейса, диалоги и настройки клиента. Пример использования объекта Context из Common API:

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let contentLanguage = context.application.contentLanguage;
    let officeTheme = context.application.officeTheme;

    console.log(`Язык контента: ${contentLanguage}`);
    console.log(`Тема Office: ${officeTheme}`);

    await context.sync();
});

Расширение пользовательского интерфейса Excel

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

Команды надстройки

Команды надстройки позволяют добавлять пользовательские кнопки и меню на ленту Excel. Пример того, как добавить пользовательскую кнопку, упрощён:

<VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
  <Hosts>
    <Host xsi:type="Workbook">
      <DesktopFormFactor>
        <ExtensionPoint xsi:type="PrimaryCommandSurface">
          <CustomTab id="MyTab">
            <Group id="MyGroup">
              <Label resid="MyGroup.Label"/>
              <Icon>
                <bt:Image size="16" resid="Icon.16x16"/>
                <bt:Image size="32" resid="Icon.32x32"/>
                <bt:Image size="80" resid="Icon.80x80"/>
              </Icon>
              <Control xsi:type="Button" id="MyButton">
                <Label resid="MyButton.Label"/>
                <Supertip>
                  <Title resid="MyButton.Title"/>
                  <Description resid="MyButton.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="ShowTaskpane">
                  <TaskpaneId>ButtonId1</TaskpaneId>
                  <SourceLocation resid="Taskpane.Url"/>
                </Action>
              </Control>
            </Group>
          </CustomTab>
        </ExtensionPoint>
      </DesktopFormFactor>
    </Host>
  </Hosts>
  <Resources>
    <bt:Images>
      <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon16.png"/>
      <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon32.png"/>
      <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon80.png"/>
    </bt:Images>
    <bt:Urls>
      <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html"/>
    </bt:Urls>
    <bt:ShortStrings>
      <bt:String id="MyGroup.Label" DefaultValue="Моя группа"/>
      <bt:String id="MyButton.Label" DefaultValue="Моя кнопка"/>
      <bt:String id="MyButton.Title" DefaultValue="Заголовок моей кнопки"/>
      <bt:String id="MyButton.Description" DefaultValue="Описание моей кнопки"/>
    </bt:ShortStrings>
  </Resources>
</VersionOverrides>

Запуск и тестирование надстройки

Чтобы протестировать надстройку, нужно запустить локальный веб-сервер и открыть Excel с загруженной надстройкой.

Запустите локальный веб-сервер

Запустите команду npm start в корневом каталоге вашего проекта, чтобы запустить локальный веб-сервер. Если вы тестируете на Mac, вам может потребоваться выполнить дополнительную команду:

npm run dev-server

Загрузите надстройку в Excel

Откройте Excel и вручную загрузите надстройку. Вот шаги:

  1. В Excel перейдите на вкладку Home.
  2. Нажмите кнопку Показать панель задач на ленте.
  3. Выберите любой диапазон ячеек на рабочем листе.
  4. В нижней части панели задач нажмите ссылку Выполнить, чтобы выполнить функцию вашей надстройки.

Пример: создание панели задач

Вот пошаговый пример создания простой панели задач надстройки, которая записывает данные на рабочий лист Excel и считывает их.

HTML-файл

Создайте HTML-файл (taskpane.html) со следующим содержимым:

<!DOCTYPE html>
<html>
<head>
    <title>Моя надстройка Excel</title>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/office.min.js"></script>
    <script src="taskpane.js"></script>
</head>
<body>
    <button id="writeToSheet">Записать на лист</button>
    <button id="readFromSheet">Считать с листа</button>
    <div id="result"></div>
</body>
</html>

Файл JavaScript

Создайте файл JavaScript (taskpane.js) со следующим содержанием:

document.addEventListener("DOMContentLoaded", function () {
    // Кнопка записи на лист
    document.getElementById("writeToSheet").addEventListener("click", writeData);

    // Кнопка чтения с листа
    document.getElementById("readFromSheet").addEventListener("click", readData);
});

async function writeData() {
    await Excel.run(async (context) => {
        let sheet = context.workbook.worksheets.getActiveWorksheet();
        let headers = [["Продукт", "Количество", "Цена за единицу", "Итого"]];
        let headerRange = sheet.get