Именование и локализация пользовательских функций

  • Статья

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

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

Пользовательская функция определяется свойством id и name в файле метаданных JSON.

  • Функция id используется для уникальной идентификации пользовательских функций в коде JavaScript.
  • Функция name используется в качестве отображаемого имени, которое отображается пользователю в Excel.

Важно!

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

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

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

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

Функция name может отличаться от функции id, например для локализации. Как правило, функции name должны оставаться теми же, что и , id если нет причин для их различий.

Функции name и id совместно используют некоторые общие требования.

  • Функция id может использовать только символы от A до Z, числа от нуля до девяти, символы подчеркивания и точки.

  • Функция name может использовать любые алфавитные символы Юникода, символы подчеркивания и точки.

  • name Функция и id должны начинаться с буквы и иметь минимальное ограничение в три символа.

Excel использует прописные буквы для встроенных имен функций (например SUM, ). Используйте прописные буквы для пользовательской name функции и id , как рекомендуется.

Функция name не должна совпадать с:

Конфликты именования

Если функция name совпадает с функцией name в надстройке, которая уже существует, в книге появится ошибка #REF! .

Чтобы устранить конфликт именования, измените в надстройке name и повторите попытку. Вы также можете удалить надстройку с конфликтующим именем. Или, если вы тестируете надстройку в разных средах, попробуйте использовать другое пространство имен, чтобы различать функцию (например NAMESPACE_NAMEOFFUNCTION, ).

Лучшие методики

  • Рассмотрите возможность добавления нескольких аргументов в функцию, а не создания нескольких функций с одинаковыми или похожими именами.
  • Избегайте неоднозначных сокращений в именах функций. Clarity важнее краткости. Выберите имя, например =INCREASETIME , а не =INC.
  • Имена функций должны указывать на действие функции, например =GETZIPCODE, а не ZIPCODE.
  • Последовательно используйте одни и те же команды для функций, выполняющих аналогичные действия. Например, используйте =DELETEZIPCODE и =DELETEADDRESS, а не =DELETEZIPCODE и =REMOVEADDRESS.
  • При именовании функции потоковой передачи рекомендуется добавить к ней примечание в описании функции или добавить STREAM в конец имени функции.

Совет

Если вы будете тестировать надстройку в нескольких средах (например, в среде разработки, в промежуточной среде, в демонстрационной среде и т. п.), рекомендуем использовать отдельный XML-файл манифеста для каждой среды. В каждом файле манифеста можно:

  • Указать URL-адреса, соответствующие среде.
  • Настроить значения метаданных, такие как DisplayName, и метки в Resources для указания среды, чтобы конечные пользователи могли определить соответствующую среду надстройки, загруженной без публикации.
  • Настроить пользовательские функции namespace, чтобы указать среду, если ваша надстройка определяет пользовательские функции.

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

Локализация пользовательских функций

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

Важно!

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

Локализация имен функций

Чтобы локализовать пользовательские функции, создайте новый файл метаданных JSON для каждого языка. В JSON-файле каждого языка добавьте name свойства и description на целевом языке. Файл по умолчанию для английского языка называется functions.json. Используйте языковой стандарт в имени файла для каждого дополнительного JSON-файла, например functions-de.json , чтобы помочь идентифицировать их.

И namedescription отображаются в Excel и локализованы. Однако id для каждой функции не выполняется локализация. Свойство id — это то, как Excel определяет вашу функцию как уникальную, и ее не следует изменять после ее установки.

Важно!

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

В следующем формате JSON показано, как определить функцию со свойством id "MULTIPLY". Свойство name и description функции локализуется для немецкого языка. Каждый параметр name и description также локализован для немецкого языка.

{
    "id": "MULTIPLY",
    "name": "SUMME",
    "description": "Summe zwei Zahlen",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "eins",
            "description": "Erste Nummer",
            "dimensionality": "scalar"
        },
        {
            "name": "zwei",
            "description": "Zweite Nummer",
            "dimensionality": "scalar"
        },
    ],
}

Сравните предыдущий json со следующим json для английского языка.

{
    "id": "MULTIPLY",
    "name": "Multiply",
    "description": "Multiplies two numbers",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "one",
            "description": "first number",
            "dimensionality": "scalar"
        },
        {
            "name": "two",
            "description": "second number",
            "dimensionality": "scalar"
        },
    ],
}

Локализация надстройки

После создания JSON-файла для каждого языка обновите XML-файл манифеста, указав значение переопределения для каждого языкового стандарта, указывающее URL-адрес каждого файла метаданных JSON. В следующем XML-коде манифеста показан языковой стандарт по умолчанию en-us с URL-адресом JSON-файла переопределения для de-de (Германия). Файл functions-de.json содержит локализованные немецкие имена и идентификаторы функций.

<DefaultLocale>en-us</DefaultLocale>
...
<Resources>
     <bt:Urls>
        <bt:Url id="Contoso.Functions.Metadata.Url" DefaultValue="https://localhost:3000/dist/functions.json"/>
          <bt:Override Locale="de-de" Value="https://localhost:3000/dist/functions-de.json" />
        </bt:url>
        
     </bt:Urls>
</Resources>

Дополнительные сведения о процессе локализации надстройки см. в разделе Локализация надстроек Office.

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

Узнайте о рекомендациях по обработке ошибок.

См. также