Документация для разработчиков
Темная тема

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
Этот метод должен выполнять дополнительные проверки, связанные с правами доступа и логикой этого поля. Например, он определен в классе поля типа "Ответственный" и "Открыто для всех".
public function process(Item $item, 
Context $context = null): Result
Основной метод, который вызывается перед сохранением элемента при выполнении операции.
public function processAfterSave
(Item $itemBeforeSave, Item $item, Context $context = null): 
FieldAfterSaveResult
Метод, в котором может быть реализована дополнительная логика, которую необходимо обработать после сохранения элемента.
В этом методе не должно вызываться сохранение элемента напрямую, новые значения полей должны быть помещены в 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()
    );
}

Пользовательские комментарии

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

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
© «Битрикс», 2001-2021, «1С-Битрикс», 2021
Наверх