Создание метаданных JSON вручную для пользовательских функций

Статья
03/15/2023

Как описано в статье обзор пользовательских функций , проект пользовательских функций должен содержать файл метаданных JSON и файл скрипта (JavaScript или TypeScript), чтобы зарегистрировать функцию, чтобы сделать ее доступной для использования. Пользовательские функции регистрируются, когда пользователь запускает надстройку в первый раз и после этого становятся доступными для одного и того же пользователя во всех книгах.

Важно!

Обратите внимание, что настраиваемые функции доступны в Excel на следующих платформах.

Office для Windows
- Подписка на Microsoft 365
- Розничный бессрочный Office 2016 и более поздних версий
Office для Mac
Office в Интернете

В настоящее время пользовательские функции Excel не поддерживаются в следующих приложениях:

Office для iPad
корпоративные бессрочные версии Office 2019 или более ранних версий

По возможности рекомендуется использовать автоматическое создание JSON вместо создания собственного JSON-файла. Автоматическое создание менее подвержено ошибкам пользователя, и файлы с yo office шаблонами уже включают это. Дополнительные сведения о тегах JSDoc и процессе автогенерации JSON см. в статье Автоматическое создание метаданных JSON для пользовательских функций.

Однако проект пользовательских функций можно создать с нуля. Для этого вам потребуется:

Запишите JSON-файл.
Убедитесь, что файл манифеста подключен к JSON-файлу.
Свяжите свойства функций id и name в файле скрипта, чтобы зарегистрировать функции.

На следующем рисунке описаны различия между использованием yo office файлов шаблонов и записью JSON с нуля.

Изображение различий между использованием генератора Yeoman для надстроек Office и написанием собственного JSON.

Примечание.

Не забудьте подключить манифест к создаваемому JSON-файлу <с помощью раздела Ресурсы> XML-файла манифеста, если генератор Yeoman не используется для надстроек Office.

Создание метаданных и подключение к манифесту

Создайте JSON-файл в проекте и предоставьте все сведения о функциях в нем, например параметры функции. Полный список свойств функции см. в следующем примере метаданных и в справочнике по метаданным .

Убедитесь, что XML-файл манифеста ссылается на JSON-файл в <разделе Ресурсы> , как показано в следующем примере.

<Resources>
    <bt:Urls>
        <bt:Url id="JSON-URL" DefaultValue="https://subdomain.contoso.com/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://subdomain.contoso.com/dist/win32/ship/index.win32.bundle"/>
            <bt:Url id="HTML-URL" DefaultValue="https://subdomain.contoso.com/index.html"/>
    </bt:Urls>
    <bt:ShortStrings>
        <bt:String id="namespace" DefaultValue="CONTOSO"/>
    </bt:ShortStrings>
</Resources>

Пример метаданных JSON

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

{
  "allowCustomDataForDataTypeAny": true,
  "allowErrorForDataTypeAny": true,
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      "description": "Add two numbers",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "type": "number",
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "first",
          "description": "first number to add",
          "type": "number",
          "dimensionality": "scalar"
        },
        {
          "name": "second",
          "description": "second number to add",
          "type": "number",
          "dimensionality": "scalar"
        }
      ]
    },
    {
      "id": "GETDAY",
      "name": "GETDAY",
      "description": "Get the day of the week",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": []
    },
    {
      "id": "INCREMENTVALUE",
      "name": "INCREMENTVALUE",
      "description": "Count up from zero",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "increment",
          "description": "the number to be added each time",
          "type": "number",
          "dimensionality": "scalar"
        }
      ],
      "options": {
        "stream": true,
        "cancelable": true
      }
    },
    {
      "id": "SECONDHIGHEST",
      "name": "SECONDHIGHEST",
      "description": "Get the second highest number from a range",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "range",
          "description": "the input range",
          "type": "number",
          "dimensionality": "matrix"
        }
      ]
    }
  ]
}

Примечание.

Полный пример JSON-файла доступен в журнале фиксаций репозитория OfficeDev/Excel-Custom-Functions GitHub. Так как проект был настроен для автоматического создания JSON, полный пример рукописного JSON доступен только в предыдущих версиях проекта.

Справочник по метаданным

allowCustomDataForDataTypeAny

Свойство allowCustomDataForDataTypeAny является логическим типом данных. Задание этого значения true позволяет пользовательской функции принимать типы данных в качестве параметров и возвращаемых значений. Дополнительные сведения см. в разделе Пользовательские функции и типы данных.

Примечание.

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

allowErrorForDataTypeAny

Свойство allowErrorForDataTypeAny является логическим типом данных. Задание значения true позволяет пользовательской функции обрабатывать ошибки в качестве входных значений. Все параметры с типом any или any[][] могут принимать ошибки в качестве входных значений, если allowErrorForDataTypeAny задано значение true. Значение по умолчанию allowErrorForDataTypeAny — false.

Примечание.

В отличие от других свойств метаданных JSON, allowErrorForDataTypeAny является свойством верхнего уровня и не содержит вложенных свойств. Пример форматирования этого свойства см. в предыдущем примере кода метаданных JSON .

функции

Свойство functions представляет собой массив объектов настраиваемых функций. В таблице ниже приведены свойства каждого объекта.

Свойство	Тип данных	Обязательное	Описание
`description`	string	Нет	Описание функции, которое отображается пользователям в Excel (например, преобразует значение по шкале Цельсия в температуру по шкале Фаренгейта).
`helpUrl`	string	Нет	URL-адрес, по которому можно получить сведения о функции (отображается в области задач). Пример: `http://contoso.com/help/convertcelsiustofahrenheit.html`.
`id`	string	Да	Уникальный идентификатор для функции. Этот идентификатор может содержать только буквы, цифры и точки, а его изменение после настройки не допускается.
`name`	string	Да	Имя функции, которое отображается пользователям в Excel. В Excel это имя функции имеет префикс пространства имен пользовательских функций, указанного в XML-файле манифеста.
`options`	объект	Нет	Позволяет настроить некоторые аспекты того, как и когда Excel выполняет функцию. Дополнительные сведения см. в разделе options.
`parameters`	array	Да	Массив, который определяет входные параметры для функции. Дополнительные сведения см. в разделе параметры .
`result`	объект	Да	Объект, который определяет тип информации, возвращаемый функцией. Дополнительные сведения см. в разделе result.

options

Объект options позволяет настроить некоторые аспекты того, как и когда Excel выполняет функцию. В таблице ниже приведены свойства объекта options.

Свойство	Тип данных	Обязательное	Описание
`cancelable`	boolean	Нет Значение по умолчанию: `false`.	Если это свойство имеет значение `true`, Excel будет вызывать обработчик `CancelableInvocation` каждый раз, когда пользователь будет предпринимать действия, которые приводят к отмене функции (например, вручную вызывает пересчет или редактирует ячейку, на которую ссылается функция). Отменяемые функции обычно используются только для асинхронных функций, которые возвращают один результат и должны обрабатывать отмену запроса на данные. Функция не может использовать свойства `stream` и `cancelable` .
`requiresAddress`	логический	Нет Значение по умолчанию — `false`.	Если `true`задано значение , пользовательская функция может получить доступ к адресу ячейки, которая ее вызвала. Свойство `address`параметра вызова содержит адрес ячейки, которая вызвала пользовательскую функцию. Функция не может использовать свойства `stream` и `requiresAddress` .
`requiresParameterAddresses`	логический	Нет Значение по умолчанию — `false`.	Если `true`задано значение , пользовательская функция может обращаться к адресам входных параметров функции. Это свойство должно использоваться в сочетании со свойством `dimensionality`результирующих объектов и `dimensionality` должно иметь значение `matrix`. Дополнительные сведения см. в разделе Определение адреса параметра .
`stream`	логический	Нет Значение по умолчанию: `false`.	Если это свойство имеет значение `true`, функция может выводить значение в ячейку несколько раз, даже если вызвана всего единожды. Этот параметр полезен для быстро изменяющихся источников данных, таких как цена акций. Функция не должна содержать оператор `return`. Вместо этого значение результата передается в качестве аргумента функции обратного `StreamingInvocation.setResult` вызова. Дополнительные сведения см. в разделе Создание функции потоковой передачи.
`volatile`	логический	Нет Значение по умолчанию — `false`.	Если `true`задано значение , функция пересчитывает каждый раз при пересчете Excel, а не только при изменении зависимых значений формулы. Функция не может использовать свойства `stream` и `volatile` . `stream` Если свойства и `volatile` имеют значение `true`, свойство volatile будет игнорироваться.

parameters

Свойство parameters представляет собой массив объектов параметров. В таблице ниже приведены свойства каждого объекта.

Свойство	Тип данных	Обязательное	Описание
`description`	string	Нет	Описание параметра. Он отображается в IntelliSense Excel.
`dimensionality`	string	Нет	Должен быть либо `scalar` (значение, отличное от массива), либо `matrix` (двухмерный массив).
`name`	string	Да	Имя параметра. Это имя отображается в IntelliSense Excel.
`type`	string	Нет	Тип данных параметра. Может быть `boolean`, `number`, `string`или `any`, что позволяет использовать любой из трех предыдущих типов. Если это свойство не указано, тип данных по умолчанию имеет значение `any`.
`optional`	логический	Нет	Если присвоено значение `true`, параметр не обязателен.
`repeating`	логический	Нет	Если `true`задано значение , параметры заполняются из указанного массива. Обратите внимание, что функции все повторяющиеся параметры считаются необязательными параметрами по определению.

result

Объект result определяет тип информации, возвращаемый функцией. В таблице ниже приведены свойства объекта result.

Свойство	Тип данных	Обязательное	Описание
`dimensionality`	string	Нет	Должен быть либо `scalar` (значение, отличное от массива), либо `matrix` (двухмерный массив).
`type`	string	Нет	Тип данных результата. Может быть `boolean`, `number`, `string`или `any` (что позволяет использовать любой из трех предыдущих типов). Если это свойство не указано, тип данных по умолчанию имеет значение `any`.

Сопоставление имен функций с метаданными JSON

Чтобы функция работала правильно, необходимо связать свойство функции id с реализацией JavaScript. Убедитесь, что существует связь, в противном случае функция не будет зарегистрирована и не будет использоваться в Excel. В следующем примере кода показано, как создать связь с помощью CustomFunctions.associate() функции . Пример определяет пользовательскую функцию add и связывает ее с объектом в файле метаданных JSON, где для свойства id установлено значение ADD.

/**
 * Add two numbers
 * @customfunction
 * @param {number} first First number
 * @param {number} second Second number
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

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

{
  "functions": [
    {
      "description": "Add two numbers",
      "id": "ADD",
      "name": "ADD",
      "parameters": [
        {
          "description": "First number",
          "name": "first",
          "type": "number"
        },
        {
          "description": "Second number",
          "name": "second",
          "type": "number"
        }
      ],
      "result": {
        "type": "number"
      }
    }
  ]
}

Имейте в виду приведенные ниже рекомендации при создании пользовательских функций в файле JavaScript и указании соответствующих сведений в файле метаданных JSON.

Убедитесь, что в файле метаданных JSON значение каждого свойства id содержит только буквы, цифры и точки.
Убедитесь, что в файле метаданных JSON значение каждого свойства id уникально в пределах файла. То есть никакие два объекта функций в файле метаданных не должны иметь одинаковое значение id.
Не изменяйте значение свойства id в файле метаданных JSON после его сопоставления с соответствующим именем функции JavaScript. Вы можете изменить имя функции, которое отображается для конечных пользователей в Excel, путем обновления свойства name в файле метаданных JSON, но никогда не следует изменять значение свойства id после его установления.
В файле JavaScript укажите настраиваемое сопоставление функций, используя CustomFunctions.associate после каждой функции.

В следующем примере показаны метаданные JSON, соответствующие функциям, определенным в предыдущем примере кода JavaScript. id Значения свойств и name находятся в верхнем регистре, что рекомендуется при описании пользовательских функций. Этот JSON необходимо добавить только в том случае, если вы подготавливаете собственный JSON-файл вручную и не используете автоматическое создание. Дополнительные сведения об автоматическом генерации см. в статье Автоматическое создание метаданных JSON для пользовательских функций.

{
  "$schema": "https://developer.microsoft.com/json-schemas/office-js/custom-functions.schema.json",
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      ...
    },
    {
      "id": "INCREMENT",
      "name": "INCREMENT",
      ...
    }
  ]
}

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

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

Создание метаданных JSON вручную для пользовательских функций

Создание метаданных и подключение к манифесту

Пример метаданных JSON

Справочник по метаданным

allowCustomDataForDataTypeAny

allowErrorForDataTypeAny

функции

options

parameters

result

Сопоставление имен функций с метаданными JSON

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

См. также

Обратная связь

Дополнительные ресурсы