Выражения

Поле-выражение — это вычисляемое поле, значение которого берётся из других полей той же записи или связанных записей. Пользователи не вводят значения в поля-выражения — их рассчитывает система.

Типичные применения:

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

  • Вычислить производное значение, например quantity * unit_price.

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

  • Составить текст для отображения, например last_name + ', ' + first_name.

Два вида выражений

Поля-выражения поддерживают два стиля синтаксиса. Каждый подходит для своего вида задач.

Точечные пути

Выражение с точечным путём переходит от текущей записи через одно или несколько полей-ссылок к значению связанной записи. Синтаксис — цепочка машинных имён полей, разделённых точками.

Пример

В документе есть поле-ссылка site, которое указывает на тип-справочник. У этого справочника есть поле region. Выражение site.region возвращает значение региона связанной записи места размещения.

Точечные пути могут проходить через несколько уровней:

site.division.company

Этот путь переходит по ссылке site, затем по ссылке division в типе места размещения и читает поле company в типе подразделения.

Выражение с точечным путём возвращает текущее значение связанной записи. Если значение связанной записи меняется, поле-выражение показывает новое значение при следующем отображении записи. Точечный путь, который ведёт по ссылке к удалённой записи, возвращает пустое значение.

Выражения на JavaScript

Для вычислений, которые не сводятся к чтению связанного значения, поля-выражения принимают JavaScript. Выражение на JavaScript обращается к значениям соседних полей текущей записи по их машинным именам и может выполнять арифметику, работу со строками или условную логику.

Примеры:

quantity * unit_price
amount > 1000000 ? 'large' : 'standard'
last_name + ', ' + first_name
Math.round(total * 100) / 100

Что доступно внутри выражения на JavaScript

Значения полей

Каждое скалярное поле (строка, целое, дробное, дата-время, выражение) той же записи доступно по своему машинному имени. Поля со сложными значениями — ссылка, набор, коллекция, сопоставление — как переменные JavaScript недоступны. Чтобы прочитать значение из связанной записи, используйте выражение с точечным путём.

Стандартные глобальные объекты JavaScript

Math, JSON, Number, String, Boolean, Array, Object, Date, RegExp, Error, parseInt, parseFloat, isNaN, isFinite, encodeURIComponent, decodeURIComponent.

Вспомогательный объект форматирования fmt

Встроенный объект с тремя методами для форматирования выводимых значений. См. Вспомогательный объект форматирования fmt ниже.

Что происходит при ошибке вычисления

Если выражение на JavaScript не даёт результата, например потому что обращается к несуществующему полю, поле-выражение остаётся пустым.

Значения NaN, Infinity и undefined считаются пустыми. Целые результаты сохраняются без десятичной точки: выражение, которое возвращает 42.0, даёт 42.

Вспомогательный объект форматирования fmt

Поля-выражения могут использовать объект fmt, чтобы форматировать числа и даты как строки.

fmt.number(value, pattern)

Форматирует число по шаблону.

Шаблон Результат для 1234567.891

#,##0.00

1,234,567.89

0.00

1234567.89

#,##0

1,234,568

#.##

1234567.89

Символы шаблона: 0 — обязательная цифра, # — необязательная цифра, , — разделитель групп, . — десятичный разделитель.

Пример выражения:

fmt.number(quantity * unit_price, '#,##0.00')

fmt.date(value, pattern)

Форматирует дату и время по шаблону.

Шаблон Пример результата

dd.MM.yyyy

15.03.2025

yyyy-MM-dd

2025-03-15

dd.MM.yyyy HH:mm:ss

15.03.2025 14:30:00

Символы шаблона: yyyy — год из четырёх цифр, yy — год из двух цифр, MM — месяц, dd — день, HH — часы (24-часовой формат), mm — минуты, ss — секунды.

fmt.currency(value)

Сокращение для fmt.number(value, '#,##0.00').

fmt.currency(quantity * unit_price)

Автозаполнение при выборе ссылки

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

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

Пример

В типе документа есть:

  • поле-ссылка site, которое указывает на справочник мест размещения;

  • поле-выражение с точечным путём site.region;

  • поле-выражение с точечным путём site.division.company.

    Когда пользователь выбирает место размещения, оба поля-выражения сразу обновляются и показывают регион и компанию выбранного места.

Автозаполнение работает и в записях верхнего уровня, и в записях внутри вложенных сущностей. Когда пользователь выбирает значение ссылки во вложенной строке, поля-выражения в этой же строке вычисляются заново.

Автозаполнение разрешает только выражения с точечными путями. Выражения на JavaScript при автозаполнении заново не вычисляются — они вычисляются при отображении записи.

Выражения внутри вложенных сущностей

Поля-выражения внутри вложенных сущностей вычисляются построчно. Каждая вложенная строка — отдельный контекст вычисления: выражение может обращаться к полям той же строки и к полям родительской записи.

Во вложенной сущности могут быть поля-выражения, которые:

  • считают итоги по строке, например quantity * unit_price в каждой позиции;

  • берут значения из связанной записи, выбранной в той же строке, например product.category, где product — поле-ссылка в строке;

  • получают значения из полей родительского уровня.

Автозаполнение работает и внутри вложенных строк: выбор значения ссылки во вложенной строке запускает автозаполнение полей-выражений в этой же строке.

Порядок вычисления

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

При сохранении записи поля-выражения не вычисляются. Сохраняется результат последнего вычисления, выполненного при отображении или автозаполнении.

Проверка

Когда администратор создаёт или редактирует поле-выражение, система проверяет выражение перед сохранением:

  • Проверка синтаксиса — выражение должно быть корректным JavaScript или корректным точечным путём.

  • Проверка ссылок на поля — идентификаторы в выражении сверяются с полями, доступными в типе сущности. Неизвестные идентификаторы выводятся как ошибки.

  • Пробное вычисление — выражение вычисляется на тестовых данных, чтобы убедиться, что оно даёт результат.

  • Проверка типа результата — тип результата сравнивается с ожидаемым типом.

Если любая проверка не пройдена, поле сохранить нельзя.

Хранимые значения

Поля-выражения доступны только для чтения.

Пользователи не могут переопределить вычисленное значение. Если процесс или интеграция записывает значение в поле-выражение, вычисленное значение заменяет его при следующем отображении записи.

Поля-выражения не входят в импорт строк данных.

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

Результаты выражений хранятся как текст.

Независимо от того, вычисляет выражение число, дату или строку, результат хранится как текстовое значение.

Связанные страницы