Начало разработки пользовательских функций Excel

  • Статья

С помощью пользовательских функций разработчики могут добавлять новые функции в Excel, определяя их в JavaScript или Typescript как часть надстройки. Пользователи Excel могут получить доступ к пользовательским функциям так же, как и к любой встроенной функции в Excel, например SUM().

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

Создание первого проекта пользовательских функций

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

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

    yo office

    Примечание.

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

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

    • Выберите тип проекта:Excel Custom Functions using a Shared Runtime
    • Выберите тип скрипта:JavaScript
    • Как вы хотите назвать надстройку?My custom functions add-in

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

    Генератор Yeoman создаст файлы проекта и установит вспомогательные компоненты Node.

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

    cd "My custom functions add-in"

  3. Выполните построение проекта.

    npm run build

  4. Запустите локальный веб-сервер, работающий на Node.js. Вы можете попробовать использовать надстройку пользовательской функции в Excel. Вам может быть предложено открыть область задач надстройки, но это необязательно. Вы по-прежнему можете запускать свои пользовательские функции, не открывая область задач надстройки.

Чтобы проверить надстройку в 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 в Интернете.

Примечание.

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

  • Если вы впервые разрабатываете надстройку Office на компьютере, в командной строке может появиться запрос на предоставление Microsoft Edge WebView исключения замыкания на себя ("Разрешить замыкания на себя локальный узел для Microsoft Edge WebView?"). При появлении запроса введите Y , чтобы разрешить исключение. Обратите внимание, что вам потребуются права администратора, чтобы разрешить исключение. После этого вам не следует запрашивать исключение при загрузке неопубликованных надстроек Office в будущем (если вы не удалите исключение с компьютера). Дополнительные сведения см. в разделе "Не удается открыть эту надстройку из localhost" при загрузке надстройки Office или с помощью Fiddler.

    Запрос в командной строке, чтобы разрешить Microsoft Edge WebView исключения замыкания на себя.

Проверка работы готовой пользовательской функции

Проект пользовательских функций, созданный с помощью генератора Yeoman, содержит некоторые готовые пользовательские функции, определенные в файле ./src/functions/functions.js. Файл ./manifest.xml в корневом каталоге проекта указывает, что все пользовательские функции принадлежат пространству имен CONTOSO.

В книге Excel проверьте, как работает пользовательская функция ADD, выполнив описанные ниже шаги.

  1. Выделите ячейку и введите =CONTOSO. Обратите внимание, что в меню автозаполнения содержится список всех функций в пространстве имен CONTOSO.

  2. Запустите функцию CONTOSO.ADD с числами 10 и 200 в качестве входных параметров, введя значение =CONTOSO.ADD(10,200) в ячейке и нажав клавишу ВВОД.

Пользовательская функция ADD вычисляет сумму двух чисел, которые вы указываете в качестве входных параметров. При вводе =CONTOSO.ADD(10,200) в ячейке должен отобразиться результат 210 после нажатия клавиши ВВОД.

Если пространство имен CONTOSO недоступно в меню автозаполнения, для регистрации надстройки в Excel выполните следующие действия.

  1. В Excel выберите Главная>надстройки, а затем — Другие надстройки.

  2. На вкладке MY ADD-INS выберите Управление моими надстройками и выберите Отправить мою надстройку.

  3. Выберите Обзор... и откройте корневой каталог проекта, созданный генератором Yeoman.

  4. Выберите файл manifest.xml и нажмите Открыть, затем нажмите кнопку Отправить.

  5. Теперь давайте оценим, как работает новая функция. В ячейке B1 введите текст =CONTOSO.GETSTARCOUNT("OfficeDev", "Excel-Custom-Functions") и нажмите клавишу ВВОД. Результат в ячейке B1 — это текущее количество звезд, отданных репозиторию Excel-Custom-Functions Github.

Если вы хотите остановить локальный веб-сервер и удалить надстройку, следуйте применимым инструкциям:

  • Чтобы остановить сервер, выполните следующую команду. Если вы использовали npm start, следующая команда также удаляет надстройку.

    npm stop

  • Если вы вручную загрузили неопубликованную надстройку, см. статью Удаление неопубликоченной надстройки.

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

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

Руководство по надстройке Excel для пользовательских функций

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

  • При многократном выполнении быстрого запуска могут возникнуть проблемы. Если в кэше Office уже есть экземпляр функции с таким же именем, в вашей надстройке возникнет ошибка при ее загрузке без публикации. Это можно предотвратить, очистив кэш Office перед запуском npm run start и обязательно выполнив запуск npm stop перед перезапуском надстройки.

    Сообщение об ошибке в Excel под названием

См. также