Введение и базовые концепции

Highload-блок хранит однотипные данные в отдельной таблице базы данных. Структуру записи задают пользовательские поля, а работать с данными из PHP-кода можно через динамический ORM-класс модуля highloadblock.

Highload-блоки подходят для плоских наборов данных: справочников, сопоставлений с внешними системами, списков характеристик и других записей без разделов.

Для публикации контента с разделами и свойствами используйте информационные блоки. Если схема данных полностью определяется кодом и развивается через миграции, создайте собственный ORM-класс. Основные принципы его разработки описаны в статье Концепция ORM.

Модель данныхМодель данных

Highload-блок связывает описание набора данных, пользовательские поля и записи.

Highload-блок -> Пользовательские поля -> Записи в отдельной таблице

Основные понятия:

• Highload-блок — описание набора данных. В нем заданы имя блока и имя таблицы для записей.

• Пользовательское поле — поле записи с кодом вида UF_*. Настройка поля определяет тип значения, обязательность и множественность.

• Запись — один элемент набора данных. Запись содержит системный идентификатор ID и значения пользовательских полей.

• Класс данных — динамический ORM-класс для таблицы конкретного Highload-блока. Через него код читает, добавляет, изменяет и удаляет записи.

Настройки Highload-блока и его записи обрабатывают разные классы. Класс Bitrix\Highloadblock\HighloadBlockTable управляет описанием блока. Динамический класс данных выполняет операции с записями.

Основные принципы работы с объектами таблиц описаны в статье Концепция ORM. Общие типы и настройки полей собраны в статье Пользовательские поля.

Схема данных в примерахСхема данных в примерах

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

Статья Связи и справочники на Highload-блоках дополнительно использует поля UF_CATEGORY и UF_CATEGORIES типа hlblock, а также служебные поля справочника. Их настройки приведены рядом с соответствующими примерами.

Когда использовать Highload-блокКогда использовать Highload-блок

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

Типовые сценарии Highload-блоков:

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

• соответствие внутренних идентификаторов кодам внешней системы,

• настройки и признаки, состав которых нужно менять через административный интерфейс,

• список данных без иерархии разделов.

Название Highload-блока не гарантирует производительность автоматически. Скорость зависит от структуры полей, индексов, фильтров, объема выборки и способа обработки данных. Рекомендации для больших наборов собраны в статье Производительность и частые ошибки.

Настройка в административном разделеНастройка в административном разделе

Highload-блоки настраивают на странице Контент > Highload-блоки.

Базовая настройка состоит из четырех шагов:

1. Создайте блок, указав имена Highload-блока и таблицы.

2. Добавьте пользовательские поля с кодами вида UF_*.

3. Настройте типы, обязательность и множественность полей.

4. Добавьте записи и проверьте значения полей в списке.

Для справочника, который будет связан со свойством информационного блока, заранее определите стабильный внешний идентификатор записи. Такой сценарий и служебные поля справочника описаны в статье Связи и справочники на Highload-блоках.

Управлять описанием блока и пользовательскими полями можно также из PHP-кода. Порядок создания, изменения, удаления и переноса структуры приведен в статье Создание, настройка и перенос Highload-блоков.

Основные точки входа в APIОсновные точки входа в API

Перед обращением к API подключите модуль highloadblock. Основные задачи распределены между несколькими объектами.

• Класс Bitrix\Highloadblock\HighloadBlockTable получает и изменяет описания Highload-блоков.

• Метод HighloadBlockTable::compileEntity() возвращает ORM-описание для таблицы выбранного блока.

• Метод getDataClass() возвращает имя динамического класса данных.

• Методы динамического класса данных выполняют операции с записями.

Пример. Получите описание Highload-блока по идентификатору и прочитайте одну запись через его класс данных. До запуска передайте в переменной $highloadBlockId идентификатор существующего блока.

use Bitrix\Highloadblock\HighloadBlockTable;
use Bitrix\Main\Loader;

if (!Loader::includeModule('highloadblock'))
{
    throw new \RuntimeException('Не удалось подключить модуль highloadblock');
}

$highloadBlock = HighloadBlockTable::getById($highloadBlockId)->fetch();

if (!$highloadBlock)
{
    throw new \RuntimeException('Highload-блок не найден');
}

$entity = HighloadBlockTable::compileEntity($highloadBlock);
$dataClass = $entity->getDataClass();

$record = $dataClass::getList([
    'select' => ['ID', 'UF_NAME'],
    'order' => ['ID' => 'ASC'],
    'limit' => 1,
])->fetch();

Метод fetch() вернет массив первой найденной записи или false, если записей нет. Поле UF_NAME должно существовать в выбранном Highload-блоке. Для другого блока замените его на код нужного пользовательского поля.

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

Права, события и вывод данныхПрава, события и вывод данных

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

Для реакции на добавление, изменение и удаление записей используйте события динамического ORM-объекта. Порядок событий, изменение данных в обработчиках и модель разрешений описаны в статье События записей и права доступа.

Для типового вывода списка и отдельной записи в публичной части используйте компоненты bitrix:highloadblock.list и bitrix:highloadblock.view. Их параметры, результат и обработка отсутствующих данных описаны в статье Вывод данных компонентами.

Связанные материалыСвязанные материалы

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

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

• Создание, настройка и перенос Highload-блоков — управление блоком, полями и переносом данных.

• Работа с записями — выборка, добавление, изменение и удаление записей.

• Связи и справочники на Highload-блоках — привязки и справочники для информационных блоков.

• События записей и права доступа — обработчики операций и проверка разрешений.

• Вывод данных компонентами — стандартный вывод списка и отдельной записи.

• Производительность и частые ошибки — индексы, объем выборки, кеширование и диагностика.