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

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

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

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

id: уникальный идентификатор, используемый в коде.
name: отображаемое имя, отображаемое пользователями. Его можно локализовать.

Важно!

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

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

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

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

Примечание.

В настоящее время унифицированный манифест для Microsoft 365 не поддерживает проекты пользовательских функций. Для проектов пользовательских функций необходимо использовать только манифест надстройки. Дополнительные сведения см. в разделе Манифест надстроек Office.

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

Функция и nameid совместно используют некоторые аналогичные правила.

Оба должны начинаться с буквы и содержать не менее трех символов.
id: допускаются только символы A–Z, 0–9, подчеркивания и точки.
name: разрешены любые алфавитные символы Юникода, символы подчеркивания и точки.

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

Избегайте совпадающих имен:

Ссылка на ячейку (A1 — XFD1048576 или R1C1 — R1048576C16384).
Макрофункт Excel 4.0 (напримерRUN, ). ECHO Полный список этих функций см. в этом справочном документе по функциям макросов Excel.

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

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

Устраните конфликты путем переименования функции или удаления другой надстройки. Для тестирования в нескольких средах используйте короткий префикс пространства имен (например ADDINNAME_FUNCTIONNAME, ).

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

Используйте дополнительные аргументы функции вместо создания нескольких похожих имен функций. Например, является более эффективным, GETNAME(firstName, middleName, lastName) чем наличие отдельных функций, таких как GETFIRSTNAME, GETMIDDLENAMEи GETLASTNAME.
Избегайте неясных сокращений. Например, проще понять, INCREASETIME чем INC.
Выберите команды действий для имен функций. Используйте GETZIPCODE вместо .ZIPCODE
Будьте последовательными. Используйте один и тот же глагол для аналогичных действий, таких как DELETEZIPCODE и DELETEADDRESS.
Для потоковых функций добавьте STREAM к имени или добавьте заметку в описание.
Используйте короткий префикс поставщика в именах функций, чтобы избежать конфликтов с другими надстройками. Например, используйте CONTOSO_GETPRICE или CONTOSO_TAX_CALC.

Совет

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

Указать URL-адреса, соответствующие среде.
Настройте значения метаданных, чтобы конечные пользователи могли определить соответствующую среду неопубликоспособной надстройки. Например:
- В унифицированном манифесте для Microsoft 365 настройте "name" свойство надстройки и "label" свойства для различных элементов управления пользовательским интерфейсом, чтобы указать среду.
- В манифесте только надстройки DisplayName настройте элемент и метки и в элементе Resources , чтобы указать среду.
Настроить пользовательские функции namespace, чтобы указать среду, если ваша надстройка определяет пользовательские функции.

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

Краткий справочник по ограничениям именования

Правило	`id`	`name`	Примечания
Допустимые символы	A–Z 0–9 `_.`	Алфавитные символы Юникода `_.`	Держите `id` все просто. Локализуйте `name`.
Должен начинаться с буквы	Да	Да	Позволяет избежать путаницы со ссылкой на ячейку.
Минимальная длина	3	3	Короткие имена снижают ясность.
Использование заглавных букв	Рекомендуется использовать все прописные буквы	Рекомендуется использовать все прописные буквы	Соответствует стилю Excel.
Локализуемый	Нет	Да	Сохраняйте `id` стабильность. Локализуйте по `name` мере необходимости.
Может имитировать адрес ячейки	Нет	Нет	Предотвращение ошибок синтаксического анализа адресов.
Зарезервированные имена макросов	Запрещено	Запрещено	Некоторые примеры: `RUN`, `ECHO`.

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

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

Важно!

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

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

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

Excel локализует name только свойства и description . Объект id не локализован и должен оставаться неизменным после установки.

Важно!

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-коде манифеста показан языковой стандарт по умолчанию en-us , а также URL-адрес файла JSON переопределения для de-de (Германия).

<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.

Поделиться через

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

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

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

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

Краткий справочник по ограничениям именования

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

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

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

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

См. также

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

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