# ctx.setValue()

Устанавливает значение текущего поля в сценариях редактируемых полей, таких как JSField и JSItem. В сочетании с `ctx.getValue()` позволяет реализовать двустороннюю привязку к форме.

## Области применения

| Сценарий | Описание |
|------|------|
| **JSField** | Запись выбранных пользователем или вычисленных значений в редактируемые пользовательские поля. |
| **JSItem** | Обновление значения текущей ячейки в редактируемых элементах таблиц или подтаблиц. |
| **JSColumn** | Обновление значения поля соответствующей строки на основе логики при рендеринге столбца таблицы. |

> **Примечание**: `ctx.setValue(v)` доступен только в контекстах RunJS с привязкой к форме. Он отсутствует в сценариях без привязки к полям, таких как рабочие процессы (FlowEngine), правила связей или JSBlock. Перед использованием рекомендуется использовать опциональную цепочку: `ctx.setValue?.(value)`.

## Определение типа

```ts
setValue<T = any>(value: T): void;
```

- **Параметры**: `value` — значение поля для записи, тип которого определяется типом элемента формы данного поля.

## Поведение

- `ctx.setValue(v)` обновляет значение текущего поля в форме Ant Design и запускает соответствующую логику связей и валидации формы.
- Если форма еще не завершила рендеринг или поле не зарегистрировано, вызов может быть неэффективным. Рекомендуется использовать `ctx.getValue()` для подтверждения результата записи.

## Примеры

### Двусторонняя привязка с использованием getValue

```tsx
const { Input } = ctx.libs.antd;

const defaultValue = ctx.getValue() ?? '';

ctx.render(
  <Input
    defaultValue={defaultValue}
    onChange={(e) => ctx.setValue(e.target.value)}
  />
);
```

### Установка значения по умолчанию на основе условий

```ts
const status = ctx.getValue();
if (status == null || status === '') {
  ctx.setValue?.('draft');
}
```

### Обратная запись в текущее поле при связи с другими полями

```ts
// Синхронное обновление текущего поля при изменении другого поля
const otherValue = ctx.form?.getFieldValue('type');
if (otherValue === 'custom') {
  ctx.setValue?.({ label: 'Пользовательский', value: 'custom' });
}
```

## Меры предосторожности

- В нередактируемых полях (например, JSField в режиме просмотра или JSBlock) `ctx.setValue` может иметь значение `undefined`. Рекомендуется использовать `ctx.setValue?.(value)`, чтобы избежать ошибок.
- При установке значений для полей связей (M2O, O2M и т. д.) необходимо передавать структуру, соответствующую типу поля (например, `{ id, [titleField]: label }`), в зависимости от конкретной конфигурации поля.

## Связанные разделы

- [ctx.getValue()](./get-value.md) — получение значения текущего поля, используется вместе с setValue для двусторонней привязки.
- [ctx.form](./form.md) — экземпляр формы Ant Design, используется для чтения или записи других полей.
- `js-field:value-change` — событие контейнера, возникающее при изменении внешнего значения, используется для обновления отображения.