Перейти к основному содержимому
Версия: 7.0

Контроллеры формы и навигатора

С формой, открытой в интерактивном представлении, код пользовательского представления или другой клиентский код на JavaScript работает через контроллер формы, а с навигатором — через контроллер навигатора.

Пользовательское представление, написанное на JavaScript, взаимодействует с формой через объект контроллера — с его помощью представление задаёт текущий объект группы, изменяет значения свойств, запрашивает подсказки и вызывает действия или скрипты на сервере. Есть три вида пользовательских представлений. React-представление получает контроллер своей проекции — члены рядом с теми самыми props.data, которые они повторяют, — и контроллер формы как его form; классическое представление находит контроллер формы как controller.form, а действие INTERNAL CLIENT получает его аргументом. Контроллер формы несёт вызовы сервера (exec / eval / evalAction / change), методы, которые делают то же, что члены представления, с тем, что рисует другой контейнер или платформа (changeOrders('i', …), changeObject('i', row), …), объявление редактирования (startEditing / stopEditing / isEditing) и пакет.

Свойства и действия адресуются по их интеграционному имени — имени на форме (либо псевдониму / интеграционному имени NEW / DELETE кнопки), тому же имени, что использует внешний JSON/REST API. Если EXTID не задал собственное имя, это имя свойства на форме, у которого отброшено всё, начиная с (, — поэтому f(a) и f(b), нарисованные в одной группе, оба будут f: интеграционное имя само по себе не уникально.

Это имя, которым представление пользуется везде: по нему ключуется props.data и по нему названы все члены контроллера. Собственные операторы формы — FILTER, ORDER и READ, выписывающий их состояние обратно, — говорят другим именем, SID свойства на форме, причём в обе стороны. Поэтому имя, которое получило представление, не является именем, которое принимает такой оператор: перекодируйте там, где эти две стороны встречаются, — в коде lsf, вызывающем оператор, а не рассчитывая, что какая-то из сторон примет оба.

Необязательные аргументы — в скобках.

Контроллеры по видам представлений​

представлениеобъявлениеточка входа JavaScriptего контроллер — это
React-представлениеDESIGN c { custom = 'Name'; }компонент, принимающий props (data, controller)props.controller
Компонент React в CUSTOMOBJECTS g = Cls CUSTOM 'Name' или PROPERTIES p CUSTOM 'Name'компонент, зарегистрированный с видом reactView, принимающий props (data, controller)props.controller.form
Окно навигатораEXTEND WINDOW System.toolbar CUSTOM 'Name';компонент, принимающий props (data, controller)props.controller — контроллер навигатора
Окно формEXTEND WINDOW System.forms CUSTOM 'Name';компонент, принимающий props (data, controller)props.controller — методы контроллера навигатора и select, close, closeAll, setEditMode, toggleFullScreen
Окно сообщенийEXTEND WINDOW System.log CUSTOM 'Name';компонент, принимающий props (data, controller)props.controller — методы контроллера навигатора и togglePin
Расположение оконNAVIGATOR CUSTOM 'Name';компонент, принимающий props (data, controller)props.controller — контроллер навигатора
Классическая CUSTOM группа объектовOBJECTS g = Cls CUSTOM 'name'колбэки render / updatecontroller.form
Классическая CUSTOM ячейка свойстваPROPERTIES p CUSTOM 'name'колбэки render / updatecontroller.form

В React-представлении формы запросы через члены контроллера или controller.form возвращают Promise. Операции окон select, close, closeAll, setEditMode, toggleFullScreen, togglePin и activate ничего не возвращают.

React-представление отрисовывает целый пользовательский контейнер, поэтому controller в его props — это собственный контроллер этого контейнера: его члены вызываются прямо на нём, а контроллер формы — его form, props.controller.form.

Локальный контроллер классического представления предоставляет контроллер формы как controller.form (группа объектов, ячейка свойства):

const total = await controller.form.exec('recalc', orderId);
await controller.form.change('customerOrder', orderId, customerId);

Строки классического представления — см. Идентификация строки, делегирование его changeProperty форме — Контроллер группы объектов. change контроллера формы строк не принимает: он называет свойство, затем значения его параметров и новое значение.

Ещё одна точка входа — действие INTERNAL CLIENT. Контроллер пользовательского редактора значения (CHANGE) также предоставляет контроллер формы в поле form.

Методы контроллера формы​

методчто делаетвозвращает
form.exec(action, ...params)выполняет именованное действиеPromise
form.eval(script, ...params)выполняет lsf-скрипт с типизированным runPromise
form.evalAction(script, ...params)выполняет тело действия (параметры $1, $2, …)Promise
form.mcpexec, eval и evalAction, выполняющие вызов так, как его выполняет инструмент eval MCP-сервера: параметры привязываются как params инструмента, а вызов завершается тем, чем отвечает инструменттри вызова
form.change(property, ...keyParams, value)задаёт глобальное свойствоPromise
form.startEditing(element)объявляет, что пользователь редактирует в element—
form.stopEditing(element)объявляет, что больше не редактирует — только если объявлен именно element—
form.isEditing(element)стоит ли это объявлениеboolean
form.changeObject(group, row), form.changeOrders(table, …), …то же, что члены, с тем, что рисует другой контейнер или платформа, по именам-строкам — между контейнерамикак у члена

Вызовы сервера​

exec, eval, evalAction и change формы — в React-представлении controller.form — выполняются на сервере и возвращают Promise. Они проходят проверку доступа и преобразуют результат в значение JS.

  • exec(action, ...params) — выполняет именованное действие. Разрешается его значением RETURN. action — это имя действия: запись CUSTOMS формы — по имени, которое у неё там, или действие проекта — по его имени, с пространством имён и сигнатурой в квадратных скобках, когда они нужны, чтобы выбрать одно: runReport[Order] среди перегруженных. Но не saveFilters(), как написали бы в скрипте: на такое имя ответ — «Action was not found».
  • eval(script, ...params) — выполняет lsf-скрипт, определяющий собственное действие run (типизированные параметры).
  • evalAction(script, ...params) — выполняет тело действия, обёрнутое в действие run, с параметрами $1, $2, ….
  • mcp — exec, eval и evalAction, выполняющие вызов так, как его выполняет инструмент eval MCP-сервера: controller.form.mcp.eval(script, ...params). Параметры привязываются так, как инструмент привязывает свои params, а вызов завершается объектом, которым отвечает инструмент, {results, status} (описан после таблицы результатов).
  • change(property, ...keyParams, value) — изменяет глобальное свойство. Последний аргумент — значение, предшествующие — ключи. Если значением свойства является объект, значением передаётся его id, и платформа присваивает объект с этим id — диалог выбора объекта открывается только при интерактивном редактировании.

Результат​

Результат преобразуется в значение JS:

Результат на сервереЗначение в JS
скалярное число, строка, логическое значение или датачисло, строка, логическое значение или Date
JSONразобранный объект или массив
JSONTEXT, XMLисходная строка
файл — изображение или свойство файлового типастрока со ссылкой для скачивания
результат с дополнительными параметрами — RETURN, выражение которого объявляет новые параметрымассив объектов {name, value}, по одному на каждый набор значений параметров — массив и при одном значении, пустой, когда значений нет: name — эти значения через запятую, value — результат, преобразованный как выше
отсутствующий результат или NULLundefined

Вызовы в формате инструмента MCP​

Вызов, выполненный так, как его выполняет инструмент eval MCP-сервера, — controller.form.mcp.eval(script, ...params), так же exec и evalAction — принимает параметры и отдаёт результат как инструмент. Параметры привязываются так, как инструмент привязывает свои params, по правилам HTTP-запроса: значение берётся своей строкой и разбирается классом параметра — поэтому строка с числом принимается как число, — а объект, в котором есть text или base64 либо указано type: 'file', — это файл при любом классе параметра. Вызов завершается тем, чем отвечает инструмент, а не результатом, преобразованным по таблице: объектом {results, status}, где status — HTTP-статус, который установило действие, 200, если оно его не устанавливало, а в results по записи на каждое значение, которое вернуло действие, — {value} со значением в виде строки, и ещё name в каждой записи результата с дополнительными параметрами.

Файл — это запись {type: 'file', fileName, extension, mimeType, size} — fileName это имя файла с расширением, а именем файла без своего имени служит file, — и в ней text — текст текстового файла, base64 — содержимое любого другого файла меньше 64 КиБ в base64, или url — ссылка для скачивания файла большего размера. Содержимое названо так же, как в файле-параметре, поэтому запись с ним можно передать в следующий вызов как есть. Текстовый файл больше 10 МиБ передаётся без текста, с truncated: true; один вызов несёт не больше 30 МиБ содержимого — сверх этого текст передаётся так же, а любой другой файл — ссылкой url.

Параметры​

Параметры передаются как обычные значения JS (число, строка, логическое значение, Date или объект/массив для параметра типа JSON) и привязываются позиционно. Файл передаётся строкой его текста или объектом: {base64, fileName, extension} для файла с нетекстовым содержимым, {text, fileName, extension} — чтобы задать текстовому файлу имя или расширение; имя и расширение необязательны. Объект lsFusion передать нельзя — передаётся его числовой id. Если параметр действия типизирован классом, платформа сама находит объект этого класса по id — ручной поиск не нужен. Дескриптор строки (row.objects) в параметре объектом не является: для типизированного классом параметра вызов завершается ошибкой, поэтому передавайте id. Ошибка — отсутствующее действие или свойство, ошибка в скрипте или исключение во время выполнения — отклоняет Promise с её сообщением.

Этот id — row.key строки этого объекта (см. Идентификация строки) либо свойство формы со значением-id. Ключ, взятый из data.<group>.byKey или data.<group>.keys, — строка, потому что ключи объекта в JS всегда строки, и его можно передать как есть: строка в числовом или типизированном классом параметре разбирается как число, пустая строка даёт NULL, а строка, которая не является числом, отклоняется.

const total = await controller.form.exec('recalc', orderId);
const doubled = await controller.form.eval('run(INTEGER a) { RETURN a * 2; }', 21); // 42
await controller.form.change('archived', orderId, true);

Сессии​

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

Проверка доступа​

По умолчанию эти вызовы ограничены так же, как внешний HTTP-API: при enableAPI = 0 вызов разрешён, только если действие или свойство помечено @@api (что заодно открывает его по HTTP), либо у пользователя есть права администратора. Чтобы контроллер конкретной формы мог вызывать выбранные действия и свойства в обход этого ограничения, их перечисляют в блоке CUSTOMS формы — тогда для доступа достаточно того, что пользователь может открыть эту форму, и явного перечисления:

FORM order 'Order'
OBJECTS o = Order
PROPERTIES(o) number, note
CUSTOMS round, format = formatSum, taxRate
;

Теперь controller.form.exec("round", 3.14159), controller.form.exec("format", 1990, "USD") и controller.form.change("taxRate", 0.2) работают на этой форме без @@api и enableAPI (React-представление вызывает то же на props.controller.form). Каждую запись можно переименовать псевдонимом (format = formatSum), снабдить префиксом ACTION, чтобы выбрать действие, и указать полностью с сигнатурой (round[NUMERIC]) для выбора перегрузки. exec требует действие, change — свойство. Параметры передаются вызывающей стороной позиционно как обычные значения. Блок меняет то, какие вызовы разрешены, а не то, как связываются параметры, и не ограничивает значения аргументов, которые передаёт вызывающая сторона, поэтому перечислять стоит только записи, безопасные при любых аргументах. eval/evalAction выполняют произвольный скрипт и остаются под ограничением.

CUSTOMS ограничивает доступ этой формой, тогда как @@api ещё и открывает действие или свойство для внешнего HTTP-API.

Закрытая форма​

Вызов после закрытия формы отклоняется с ошибкой Form is closed — он никогда не зависает, — поэтому await на закрытой форме попадает в ветку catch. Форма считается закрытой, когда её закрыл сервер. Вызов, сделанный, пока закрытие ещё не завершено, — клиент уже убрал форму со страницы по нажатию действия, которое может её закрыть, а сервер ещё не ответил, — отправляется и выполняется после запроса закрытия: если сервер в закрытии откажет, форма вернётся вместе с тем, что сделал вызов, поэтому ввод, который представление фиксирует в момент закрытия, не теряется.

Операции между контейнерами​

То, что рисует другой контейнер или платформа, представление меняет через контроллер формы, controller.form, — по именам, строками, которые проверяются при вызове. Каждый его метод делает то же, что член представления, — те же аргументы после имён, те же проверки и отказы, а отказ цитирует вызов формы (controller.form.changeOrders('i'): order 0: unknown property 'x' of object group 'i'), — с состоянием формы, кто бы его ни рисовал: контейнер, который рисует часть, показывает изменение до того, как вызов вернётся, как при вызове собственного члена, а таблица, дерево, тулбар или панель фильтров платформы — так же, как собственные правки формы. Вызов внутри пакета уходит с ним; вызов, который обращается к серверу, в пакете отклоняется, как у члена. Каждый возвращает то же, что его член.

методделает то же, что этот членимя
changeObject(group, row[, {selection}])<group>.change(row[, {selection}])SID группы
changeColumn(group, column[, {selection}]) / selectAll(group)<group>.properties.change(column[, {selection}]) / <group>.selectAll() — выделение строк, которые рисует другой контейнер, или таблицы платформыSID списочной группы вне дерева
copy(group) / paste(group, text)<group>.copy() / <group>.paste(text) — буфер обмена строк, которые рисует другой контейнер, или таблицы платформыSID списочной группы вне дерева
expand(group, row) / collapse(group, row) / expandAll(group) / collapseAll(group)<group>.expand(row) / .collapse(row) / .expandAll() / .collapseAll()SID группы дерева
expandCurrent(tree) / expandTree(tree)<tree>.expandCurrent() / expandTree() его тулбараимя дерева
changeOrders(table, order) / changeOrders(table, orders)<table>.orders.change(…)SID списочной группы или имя дерева
changeFilters(table, condition) / changeFilters(table, conditions)<table>.filters.change(…) (пользовательские фильтры)SID списочной группы или имя дерева
changeFilter(property, value[, options])<group>.filter.<property>.change(value[, options]) — условие фильтра свойства'<group>.<property>'
addFilter(table) / applyFilters(table) / resetFilters(table)addFilter() / applyFilters() / resetFilters() управляющих элементов фильтровSID списочной группы или имя дерева
changeFilterControlsVisible(table, shown)filterControlsVisible.change(shown) тулбараSID списочной группы или имя дерева
changeFilterGroup(filterGroup, index)<group>.<filterGroup>.change(index)имя группы фильтров
changeViewFilters(group, conditions)<group>.viewFilters.change(conditions) — фильтры представления строк, которые рисует другой контейнер; там, где их рисует платформа, отклоняетсяSID списочной группы вне дерева
getCount(group) / getSum(group, property)<group>.getCount() / .getSum(property) — PromiseSID списочной группы
changeManual(group, on) / update(group) / changeListView(group, name)<group>.manual.change(on) / .update() / .listView.change(name)SID списочной группы
export(table)<table>.export()SID списочной группы или имя дерева
changeProperty(property[, row][, value])классический changeProperty, аргументы читаются так же: значение задаётся или запускается событие изменения — на текущем объекте или на переданной строке'<group>.<property>', свойство пустой группы — по его имени
getValues(property, value[, {row, mode, count}])<group>.<property>.getValues(value[, options]), список подсказок — Promise; строка — строка данных или её дескриптор objects, без неё — текущий объект, а у свойства пустой группы строк нет; свойство, которое форма скрывает, спрашивается всё равно, как changeProperty его меняетто же

changeFilter отклоняется, если дизайн удаляет компонент FILTER свойства или содержащий его контейнер. Через changeFilters по-прежнему можно задать условие на это свойство.

Строка называется тем, что есть у представления: строкой данных или её дескриптором objects — строки своих данных или результата запроса (getValues в режиме objects). Ключ называет строку только в представлении, которое рисует строки, через его член, поэтому контроллер формы ключей не принимает. У группы дерева нет своих сортировок, пользовательских фильтров и тулбара: они у дерева, называются именем дерева, а каждое свойство в его сортировках и условиях — как <group>.<property>. Команды управляющих элементов фильтров уходят во ввод фильтров таблицы, кто бы ни рисовал условия и где бы ни были сами элементы, если они вообще есть; там, где платформа ввода не делает (условия рисует она, а её тулбар выключает фильтры), применение и сброс уходят прямо в пользовательские фильтры таблицы, а добавление отклоняется: строку добавить некуда. changeFilterControlsVisible работает там, где элементы управления платформы показывает и скрывает кнопка тулбара. Текущий объект, выбранный там, где строки рисует платформа, сразу становится текущим для формы — то, что у формы спрашивают дальше, спрашивается про эту строку, — а таблица платформы переходит на неё с ответом сервера.

// боковая панель сортирует, фильтрует и выбирает в строках, которые рисует другой контейнер
controller.form.changeOrders('i', {property: 'price', desc: true});
controller.form.changeFilter('i.price', 100, {compare: '>='});
controller.form.changeFilterGroup('stock', 0);
controller.form.changeObject('i', found.objects); // строка, найденная запросом

Запрос значений​

getValues запрашивает у сервера ограниченный список подсказок для свойства — список подсказок, а не полный SELECT DISTINCT — и возвращает Promise ответа, { data: [ { displayString, rawString, objects }, ... ] }. Слишком короткий для поиска на сервере запрос отвергает его с сообщением, которое тогда показывает редактор платформы, — «Слишком короткая строка для поиска», на языке пользователя, — как form.exec и form.eval отвергаются с сообщением сервера. Ответ, который сервер дал, ещё не убедившись, что несохранённые изменения формы на него не влияют, несёт ещё и more — Promise окончательного ответа.

controller.<group>.<property>.getValues(value[, {row, mode, count}]);
controller.form.getValues('<group>.<property>', value[, {row, mode, count}]); // то же, по имени свойства
  • value — вводимая строка запроса для сопоставления.

  • row — необязательная строка, которой ограничивается запрос: член списочного свойства принимает строку данных, дескриптор или ключ строки, контроллер формы — строку данных или её дескриптор objects названной группы, но не ключ. Без неё запрос делается для текущего объекта; у свойства пустой группы строки нет. Контроллер формы спрашивает и свойство, которое форма скрывает, — как changeProperty его меняет, — а член, пока его свойство скрыто, отказывает.

  • mode — одно из:

    modeрезультатitem.objects
    'objects' (по умолчанию)подходящие OBJECTS свойства — выбор объектанепосредственный дескриптор objects этого объекта
    'values'различные значения свойстваnull (используйте displayString / rawString)
    'change'подсказки времени правки свойствазависит от свойства

    'change' отражает то, как свойство редактируется — пользовательский список INPUT, ограничение notNull или пользовательское действие изменения, — а не уже имеющиеся различные значения. Для свойства, которое в этом контексте изменить нельзя (например, только для чтения или вычисляемое без действия изменения), таких подсказок нет и Promise отвергается, тогда как 'values' всё равно вернёт его различные значения.

  • count — увеличивает число запрашиваемых элементов, для постраничной загрузки.

Запрос, переданный не строкой, неизвестный вызову параметр или параметр со значением не из перечисленных выше вызывают исключение при вызове. Сервер выполняет запросы подсказок формы по одному: запрос, который он ещё выполняет, когда приходит следующий, отменяется, а его Promise отвергается с Error, у которого cancelled равно true. Ответ всё же может прийти и после ответа более позднего запроса, поэтому представление, запрашивающее подсказки по мере ввода, проверяет, что ответ относится к показанному запросу.

item.objects из результата режима 'objects' можно передать напрямую обратно как строку, чтобы действовать с выбранным объектом: в .change группы, чтобы сделать его текущим, или как row в .change(value, row) или .exec(row) списочного свойства. Значением он не бывает никогда: дескриптор, переданный как значение FK, молча выставляет NULL (см. Форматы значений), а FK задаётся id объекта.

Пакет​

batch(fn) выполняет fn и отправляет изменения, сделанные в ней членами, вместе, когда fn вернётся. Вызов в пакете делается в момент вызова, как и вне пакета, — читается, проверяется и сразу показывается, поэтому читает состояние таким, каким его оставили вызовы до него: две сортировки, заданные по одной, или два toggle одного узла продолжают друг друга. Ждут только запросы: когда fn вернётся, изменения членов уходят ОДНИМ запросом: сервер делает их в порядке вызовов — значения свойств, текущий объект группы и её выделенные строки и колонки, её сортировки, её пользовательские фильтры и фильтры представления, её режим обновления и вид, в котором показаны её строки, фильтры, выбранные в её группах фильтров, узлы дерева — и отвечает один раз, перечитывая форму один раз за все. Изменение пользовательских фильтров, которое придерживает ручной режим применения, ждёт применения, и в пакете тоже. Действие, запущенное через exec() внутри пакета, выполняется в этом же запросе, который, как изменение свойства, не задерживает пользователя. Внутри fn вызывайте только члены и методы контроллера формы: перевод фокуса, изменение DOM или события, посланные компонентам платформы, заставляют платформу отправлять свои запросы — редактор, потеряв фокус, сохраняет значение, — а на них пакет не рассчитан. Пакет несёт только изменения: внутри fn getValues отклоняется, а серверный вызов контроллера формы (form.exec, form.eval, form.evalAction, form.change) — тоже, их Promise отвергается, как и вызовы тулбара, которые обращаются к серверу: getCount, getSum, export (и у дерева), а также copy и paste группы — их Promise отвергается с причиной отказа, — и методы контроллера формы, которые за ними стоят; делайте их до пакета или после. filterControlsVisible.change сразу показывает или прячет управляющие элементы. addFilter, applyFilters и resetFilters управляющих элементов фильтров входят в пакет, как filters.change, а expandCurrent дерева — и над штатным деревом expandTree его тулбара — раскрывают его узлы и входят в пакет, как expandAll: expandCurrent раскрывает строку, которую раньше в том же пакете сделал текущей change(row). Редактор условия, которое filterControlsVisible.change начинает на пустой панели платформы, а addFilter — на её панели, открывается и получает фокус, когда пакет отправлен. props.data внутри fn не меняется: то, что меняет пакет, видно, когда он закончится.

Ошибка в аргументах вызывает исключение при вызове, и в пакете, и на закрытой форме, а исключение внутри fn — отклонённый вызов или собственное исключение представления — заканчивает пакет: сделанное до исключения отправляется, как ушло бы и вне пакета, а исключение доходит до представления. Пакет — формы, какой бы контроллер его ни начал: batch React-представления, form.batch формы, batch классического представления. Пакет, начатый внутри другого пакета, — часть его и отправляется, когда закончится внешний, — сделанное им до исключения тоже, — а член другого представления или метод контроллера формы, вызванный внутри fn, уходит с этим пакетом. Перед тем как выполнить fn, форма отдельным запросом отправляет строку, на которую пользователь перешёл в таблице или дереве, которые рисует платформа, — иначе форма отправляет её чуть позже, — у каждой группы формы: она отправляется независимо от того, пройдёт ли запрос пакета.

fn выполняется сразу: функция, возвращающая Promise, — async, чьи вызовы после await пришлись бы на время, когда пакет уже закончился, — отклоняется, а сделанное ею до await отправляется; сначала дождитесь, потом начинайте пакет. Собственный Promise пакета, который возвращает вызов, сделанный в fn, не отклоняется, поэтому fn можно записать этим вызовом: controller.batch(() => controller.o.note.change('checked')).

Пакет — и не транзакция: его изменения делаются в сессии формы, как правки пользователя, а на сервере — одно за другим: упавшее останавливает остальные, а сделанные до него остаются в сессии; в базу они попадают, когда сессия применяется.

Когда изменение падает, значения свойств, которые менял пакет, показываются такими, какими были до пакета, а те, что сервер успел сделать до упавшего изменения, приходят с его следующим ответом. Остальное, что изменил пакет, — текущий объект группы, её текущая колонка и выделенные колонки, её сортировки, пользовательские фильтры и фильтры представления, её режим обновления и вид, в котором показаны её строки, фильтры, выбранные в её группах фильтров, узлы дерева, которые он открыл или закрыл, — остаётся таким, каким его показал пакет, сделал это сервер или нет: их сервер присылает, только когда меняет их сам, поэтому после падения задайте их заново там, где это важно, — пользовательские фильтры другим списком, чем у пакета, режим обновления и вид — через другой: заданное пакетом считается уже отправленным и заново не отправляется.

batch(fn) возвращает Promise своего единственного запроса, и вызов изменяющего члена, сделанный в fn, возвращает тот же самый Promise, поэтому падение отвергает один Promise, а не по одному на вызов. Пакет, который не делает запроса, выполняется сразу. На закрытой форме он отвергается с Form is closed, и fn не выполняется.

batch(fn) отправляет несколько изменений вместе. Каждое — собственный вызов члена, как и вне пакета:

await controller.batch(() => {
controller.o.note.change('checked');
controller.o.qty.change(5, row);
}); // Promise единственного запроса: оба изменения сделаны, ответ пришёл

Форматы значений​

.change свойства ведёт себя одинаково в пакете и вне его, а формат зависит от того, что задаётся в значение:

значениекак передаётся
примитивнапрямую: число — для числовых типов, строка, JS-Date или строка из значения поля ввода даты этого класса ('2026-11-15', '10:30', '2026-11-15T10:30') — для DATE / TIME / DATETIME / ZDATETIME, логическое значение, null — для очистки
интервал, COLORстрокой в том виде, в каком значение приходит в представление: <from>.<to> с границами в миллисекундах, #rrggbb. Значение другой формы отклоняется
JSONJS-объект или массив (сериализуется в JSON)
объект (значение FK)id целевого объекта — row.key его строки (для группы с одним объектом это уже его числовой id) либо id-свойство на форме (например, LONG(obj)), но не дескриптор

Значение, полученное представлением, можно передать обратно в change члена или как value условия без преобразований, кроме файлового: ссылка для скачивания — не файл. Строка даты или времени не содержит часового пояса и должна иметь формат поля ввода своего класса, как в таблице. Любая другая строка отклоняется, как и день, которого нет в месяце.

к сведению

Передача дескриптора (otherRow.objects) в качестве значения FK молча выставляет NULL, без ошибки. Дескриптор нужен только для аргумента-строки вызова члена и для <group>.change. Чтобы задать FK, передавайте id целевого объекта.

В обратную сторону формат тот же: значение объектного свойства приезжает в строку данных этим же числовым id, поэтому его можно сравнить с row.key целевой строки (в группе с одним объектом) или передать обратно значением FK без преобразований.

// перенос объекта к другому родителю и правка примитива вместе:
// значение FK — id целевого объекта (row.key целевой строки), значение-примитив — напрямую
controller.batch(() => {
controller.i.parent.change(targetColumn.key, item);
controller.i.value.change(5, item);
});

Объявление редактирования​

Пока форма редактирует, привязка, у которой область editing задана по умолчанию, не срабатывает для события, пришедшего изнутри редактируемого элемента: ENTER не переводит фокус на следующий компонент, ESCAPE не закрывает модальное окно, а горячая клавиша, заданная через CHANGEKEY, не выполняется. Привязка, объявленная с editing=all, срабатывает в любом случае.

Редакторы, созданные ею самой, форма знает. Поля, которое представление нарисовало себе само, она не знает, поэтому представление объявляет его на контроллере формы:

  • startEditing(element) — с этого момента пользователь редактирует в element;
  • stopEditing(element) — пользователь больше не редактирует в element, причём объявление снимается, только если объявлен именно element;
  • isEditing(element) — объявлен ли element.

Объявление на форме одно: объявление другого элемента заменяет предыдущее. Пока открыт собственный редактор формы, он имеет приоритет над объявлением, и объявление читается снова, когда это редактирование заканчивается.

Пока объявление стоит, перечисленные привязки не срабатывают для событий из element и из всего, что внутри него. Представление, которое ничего не объявило, сохраняет прежнее поведение: ENTER переводит фокус на следующий компонент, ESCAPE закрывает окно — из нарисованного представлением поля так же, как откуда угодно ещё.

Собственный редактор свойства начинает редактирование с первого набранного символа, а не по фокусу.

Объявление на обёртке покрывает все поля внутри неё — в том числе вложенный дочерний компонент, который рисует платформа и редактор, который платформа рисует в нём. Если это не нужно, объявляйте более узкий элемент.

Снимать объявление — обязанность представления, и не только по blur: снимайте его, когда элемент удаляется или представление размонтируется. Забытое объявление не даёт этим привязкам срабатывать для событий внутри этого элемента, пока форма открыта.

Объявление не начинает редактирование свойства: коммитить и отменять нечего, и ENTER ничего не сохраняет. Чтобы из представления редактировалось свойство, поставьте его через <Platform name/> — платформа нарисует там свой редактор, и объявлять ничего не нужно.

Отдельная клавиша, нужная представлению независимо от состояния редактирования, — его собственная горячая клавиша — это другое: остановите событие в обработчике (stopPropagation), и форма его не получит.

Действие INTERNAL CLIENT, помещённое в NAVIGATOR, тоже получает контроллер, но навигаторный: формы здесь нет, поэтому нет и перечисленных выше методов формы. Есть четыре серверных вызова — exec, eval, evalAction, change, и options для первых трёх, — которые выполняются в собственной сессии навигатора, новой на каждый вызов и не применяемой автоматически, поэтому отдельный вызов change здесь не сохраняет изменение. Действие или скрипт может применить свои изменения через APPLY. Каждый из них возвращает Promise. И есть activate:

  • activate(canonicalName[, event]) — делает то же, что нажатие на этот элемент навигатора: выбирает папку либо выполняет действие, открывая его форму так же оптимистично. canonicalName — каноническое имя элемента. event — событие нажатия, React-овское или браузерное, и при вызове из кода, у которого события нет, его можно не передавать.

Компоненты React окна навигатора, окна форм, окна сообщений и расположения окон получают все пять методов прямо в props.controller. Окно форм и окно сообщений также сохраняют собственные операции с окном.

Активация несуществующего элемента или скрытого SHOWIF — собственным или папки над ним — бросает исключение. activate ничего не возвращает и не сообщает о завершении, как и нажатие.

window.openMonthlyReport = function (controller) {
controller.activate('Reporting.monthly');
};
openMonthlyReport 'Отчёт за месяц' () { INTERNAL CLIENT 'openMonthlyReport'; }

NAVIGATOR {
NEW openMonthlyReport WINDOW system PARENT;
}

Идентификация строки​

Метод, адресующий строку, принимает одно из:

  • объект строки данных, полученный представлением (из props React либо из списка update классического представления);
  • копию такой строки через spread или Object.assign — перечислимый дескриптор objects копируется вместе с ней, поэтому копия разрешается в тот же объект;
  • непосредственный дескриптор objects — row.objects либо item.objects из результата getValues в режиме 'objects';
  • ключ, который дала строке проекция, — row.key либо ключ из data.<group>.keys / byKey. Строку принимают только там, где рисуются строки её группы, поэтому у этого представления всегда есть byKey, в котором ищется ключ: он ищется среди строк группы самого члена, а ключ, не называющий там ни одной строки, завершается ошибкой. Именно это позволяет представлению вернуть то, что оно получило: byKey — JS-объект, и Object.keys() по нему даёт строки, так что прошедший через него ключ больше не несёт того типа, которым был записан row.key. У классического представления такого индекса нет, поэтому его changeProperty принимает строку или её дескриптор.

При этом для группы с одним объектом пользовательского класса значение row.key численно равно id этого объекта, поэтому его можно передать как id целевого объекта в серверный вызов или в значение FK — отдельное свойство для собственного id строки создавать не нужно.

Если явный аргумент-строка не является ни одним из них, платформа не подставляет молча текущую строку: вызов завершается ошибкой с указанием того, что ожидалось, вместо действия над другой строкой. Не принимается и строка другой группы: controller.<group>.change(row) и change(value, row) / exec(row) члена списочного свойства — оба говорят, чья строка имеется в виду, — группы члена, — а строка другой группы несёт объекты только той группы, поэтому остальные были бы взяты из текущих и вызов пришёлся бы на строку этой группы, которую никто не называл. Внутри дерева строка группы НИЖЕ в этом смысле не является строкой другой группы: её ключ — весь путь до неё, поэтому она называет ровно одну строку каждой группы выше, и там она принимается — ровно так же, как её принимает <group>.change.