Field

Общее

У элементов разных типов сущностей CRM есть поля с разными кодами, но одинаковым набором бизнес-логики.

Чтобы не дублировать вызовы одинаковых кусков в операциях разных типов в новом API было решено вынести это в отдельную иерархию классов.

Имя класса-наследника указывается в фабрике в методе getFieldsSettings().

Если наследник не указан, то всё равно работает базовый класс.

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

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

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

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

Атрибуты

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

\CCrmFieldInfoAttr::Hidden - Поле недоступно в REST и игнорируется при слиянии дубликатов.
\CCrmFieldInfoAttr::NotDisplayed - Поле не выводится в интерфейсе детальной карточки (но может быть доступно в списках).
\CCrmFieldInfoAttr::ReadOnly - Значение поля не может быть изменено пользователем.
\CCrmFieldInfoAttr::Immutable - Значение поля может быть заполнено пользователем только при создании.
\CCrmFieldInfoAttr::UserPKey - Поле является первичным ключом. Редко используется.
\CCrmFieldInfoAttr::Required - Поле является обязательным.
\CCrmFieldInfoAttr::Multiple - Поле является множественным.
\CCrmFieldInfoAttr::Dynamic - Поле является пользовательским полем.
\CCrmFieldInfoAttr::Deprecated - Поле помечено как устаревшее (выводится в REST).
\CCrmFieldInfoAttr::Progress - Поле содержит информацию о стадии элемента. Редко используется.
\CCrmFieldInfoAttr::HasDefaultValue - Поле имеет значение по умолчанию.
\CCrmFieldInfoAttr::AutoGenerated - Значение поля генерируется автоматически при создании элемента.
\CCrmFieldInfoAttr::Unique - Значение поля должно быть уникальным в рамках таблицы элементов.
\CCrmFieldInfoAttr::CanNotBeEmptied - Если пользователь очищает значение этого поля, то это изменение не применяется - при сохранении сбрасывается в исходное состояние.

Методы

Метод	Описание	С версии
public function __construct (string $name, array $description) $name - код поля, как он называется в таблице элементов; $description - массив с описанием поля следующей структуры: TYPE - тип поля, возможные значения перечислены в константах класса `TYPE_`; TITLE* - языковое название поля; ATTRIBUTES - массив с перечислением атрибутов поля; SETTINGS - массив с дополнительными настройками поля произвольной структуры; USER_FIELD - массив с дополнительными настройками поля произвольной структуры; SETTINGS - описание настроек пользовательского поля, если это поле является пользовательским.	Конструктор. Напрямую вызывать его не рекомендуется, для получения полей надо пользоваться методами фабрики.
public function isValueCanBeChanged(): bool	Вернет true, если значение поля может быть изменено пользователем (проверяются наличие атрибутов `\CCrmFieldInfoAttr::ReadOnly` и `\CCrmFieldInfoAttr::Immutable`).
public function processWithPermissions (Item $item, UserPermissions $userPermissions): Result $item - элемент; $userPermissions - сервис прав доступа.	Этот метод должен выполнять дополнительные проверки, связанные с правами доступа и логикой этого поля. Например, он определен в классе поля типа "Ответственный" и "Открыто для всех".
public function process(Item $item, Context $context = null): Result $item - элемент; $context - контекст выполнения.	Основной метод, который вызывается перед сохранением элемента при выполнении операции.
public function processAfterSave (Item $itemBeforeSave, Item $item, Context $context = null): FieldAfterSaveResult $itemBeforeSave - элемент в состоянии до его сохранения; $item - элемент в актуальном состоянии; $context - контекст выполнения.	Метод, в котором может быть реализована дополнительная логика, которую необходимо обработать после сохранения элемента. В этом методе не должно вызываться сохранение элемента напрямую, новые значения полей должны быть помещены в `FieldAfterSaveResult`.
public function isItemValueEmpty(Item $item): bool	Вернет true, если значение этого поля у элемента $item не заполнено.
public function isValueEmpty($fieldValue): bool	Вернет true, если значение $fieldValue для этого поля расценивается как не заполненное.
public function getName(): string	Вернет код поля.
public function setName(string $name): Field	Запишет новый код поля $name.
public function getTitle(): string	Вернет название поля.
public function setTitle(string $title): self	Запишет новый код поля $title.
public function getType(): string	Вернет тип поля.
public function setType(string $type): Field	Запишет новый тип поля $type.
public function getAttributes(): array	Вернет набор атрибутов поля.
public function setAttributes(array $attributes): Field	Запишет новый набор атрибутов поля $attributes (перезапишет полностью).
public function getSettings(): array	Вернет набор настроек поля.
public function setSettings(array $settings): Field	Запишет новый набор настроек поля $settings.
public function isUserField(): bool	Вернет true, если поле является пользовательским.
public function getUserField(): array	Вернет описание настроек пользовательского поля.
public function isAutoGenerated(): bool	Вернет true, если значение поля генерируется автоматически.
public function isMultiple(): bool	Вернет true, если поле является множественным.
public function isDisplayed(): bool	Вернет true, если поле должно отображаться в детальной карточке элемента.
public function isRequired(): bool	Вернет true, если поле является обязательным.
public function toArray(): array	Вернет массив с описанием параметров поля, структура которого аналогична аргументу $description конструктора.
public function isFileUserField(): bool	Вернет true, если поле является пользовательским с базовым типом "файл".
public function getValueNotValidError(): Error	Вернет ошибку о том, что поле заполнено некорректно.
public static function getRequiredEmptyError (string $fieldName, ?string $title = null): Error $fieldName - код поля; $title - название поля.	Вернет ошибку о том, что обязательное поле не заполнено.
public function getValueNotUniqueError(): Error	Вернет ошибку о том, что значение поля не является уникальным.

Наследники

На данный момент есть следующие типы полей:

Поле	Описание
Field\Assigned	Ответственный. Если при создании у пользователя есть право на создание только "Своих" элементов, то в значение поля будет принудительно записан пользователь, производящий изменение (взят из контекста). Если поле не заполнено, то туда будет принудительно записан текущий пользователь (взят из контекста).
Field\Category	Направление. Если поле изменено, то проверяется, что идентификатор является корректным идентификатором направления соответствующего типа. После сохранения, если поле изменено, проивзодится очистка атрибутов прав доступа.
Field\Closed	Закрыто. Автоматически заполняется в зависимости от семантики текущей стадии.
Field\CloseDate	Дата закрытия. Автоматически заполняется текущей датой, если значение этого поля не заполнено и значение поля "Закрыто" стоит в true.
Field\CreatedBy	Кем создано. Автоматически заполняется текущим пользователем (из контекста) при создании. В остальных случаях принудительно сбрасывается в исходное состояние.
Field\CreatedTime	Время создания. Автоматически заполняется текущее время при создании нового элемента.
Field\MovedBy	Кем передвинут. Автоматически заполняется текущим пользователем (из контекста) при смене стадии.
Field\MovedTime	Когда передвинуто. Автоматически заполняется текущее время при смене стадии.
Field\Number	Номер. Если поле было очищено при изменении, то туда принудительно записывается идентификатор элемента. При создании номер генерируется автоматически согласно настройкам нумератора. .
Field\Observers	Наблюдатели. Обновляет состав привязанного чата.
Field\Opened	Открыто для всех. Если пользователь имеет право на создание / изменение только открытых для всех элементов, то в это поле принудительно записывается true.
Field\Opportunity	Сумма. Если включен автоматический расчет суммы, то значение расчитывается на основе состава товарных позиций через сервис расчетов.
Field\OpportunityAccount	Сумма для отчетов. Значение заполняется на основе валюты отчетов и значения поля "Сумма".
Field\PersonTypeId	Тип плательщика. Заполняется автоматически на основе того, привязана ли компания к элементу.
Field\PreviousStageId	Предыдущая стадия. Заполняется автоматически при смене стадии.
Field\Stage	Стадия. Заполняется автоматически при смене стадии. При изменении значения поля проверяется, что указан корректный статус, относящийся к списку стадий текущего направления элемента. Если изменено поле "Направление", а новая стадия не указана, то значение заполняется автоматически первым статусом той же семантики нового направления.
Field\TaxValue	Сумма налогов. Заполняется автоматически на основании списка товарных позиций через сервис расчетов.
Field\UpdatedBy	Кем обновлен. Автоматически заполняется текущим пользователем из контекста.
Field\UpdatedTime	Когда обновлено. Автоматически заполняется текущим временем.

Примеры

use Bitrix\Crm\Service;
use Bitrix\Crm\Item;

$factory = Service\Container::getInstance()->getFactory(\CCrmOwnerType::Quote);

$opportunityField = $factory->getFieldsCollection()->getField(
	Item::FIELD_NAME_OPPORTUNITY
);
if (
	$opportunityField->isValueEmpty($value)
	&& $opportunityField->isRequired()
)
{
	$error = $opportunityField::getRequiredEmptyError(
		$opportunityField->getName(),
		$opportunityField->getTitle()
	);
}