Обзор
Плагин Advanced Custom Fields содержит множество полезных типов полей, таких как text, image и WYSIWYG. Однако при работе над проектом может потребоваться создать новый тип поля, чтобы сохранять и загружать уникальные данные.
Это руководство покажет, как создать новый тип поля для плагина ACF.
Скачать
Чтобы упростить задачу, мы подготовили подробный шаблон для создания типа поля ACF, а также NPM-скрипт, который поможет вам начать работу ещё быстрее.
Шаблон ACF Example Field Type на GitHub
Пожалуйста, скачайте или клонируйте репозиторий ACF Example Field Type. Альтернативно, вы можете нажать зелёную кнопку «Использовать этот шаблон», чтобы создать новый репозиторий на основе этого шаблона.
https://github.com/AdvancedCustomFields/acf-example-field-typeПосле того как вы скачаете шаблон, следуйте инструкциям в README, чтобы начать работу над собственным типом поля.
Настройка
Вся логика внешнего вида и функциональности вашего поля определяется в файле acf-FIELD-NAME/class-PREFIX-acf-field-FIELD-NAME.php. Этот класс расширяет класс acf_field, который полон мощных функций, позволяющих настраивать, как данные сохраняются и отображаются! У каждой функции есть документация в виде внутренних комментариев, поэтому лучше открыть файл и прочитать его сверху вниз.
Ниже приведён краткий обзор функций:
| Название | Описание |
|---|---|
__construct | Функция инициализации, которая задаёт данные поля, такие как имя, метка, категория и значения по умолчанию |
render_field_settings | Создаёт дополнительные настройки для вашего поля. Они видны при редактировании поля |
render_field | Создаёт HTML-интерфейс для вашего поля |
input_admin_enqueue_scripts | Подключает CSS и JavaScript, которые помогают функции render_field() |
input_admin_head | Добавляет встроенные CSS и JavaScript, которые помогают функции render_field() |
input_form_data | Добавляет скрытый встроенный HTML |
input_admin_footer | Добавляет встроенные CSS и JavaScript, которые помогают функции render_field() |
load_value | Этот фильтр применяется к $value после загрузки из базы данных |
update_value | Этот фильтр применяется к $value перед сохранением в базе данных |
format_value | Этот фильтр применяется к $value перед возвратом в API шаблона |
validate_value | Этот фильтр используется для проверки значения перед сохранением |
delete_value | Это действие срабатывает после удаления значения из базы данных |
Приведённые выше функции — лишь часть возможностей класса acf_field. Пожалуйста, прочитайте расширенные комментарии, расположенные над каждой функцией, чтобы узнать больше.
Экранирование HTML
Некоторые типы полей могут напрямую выводить потенциально небезопасный HTML, например iframe или теги script.
Начиная с ACF 6.2.5, где такие элементы автоматически удалялись при использовании шорткода ACF или the_field(), ACF поддерживает экранирование собственного HTML типами полей по запросу. Для этого во второй параметр метода format_value передаётся значение, и если оно true, нам нужна безопасная для HTML версия вывода.
В этом случае ваш тип поля должен гарантировать, что злоумышленник не сможет отрендерить вредоносный HTML на фронтенде, изменив сырое значение в базе данных. Например, базовое поле WYSIWYG делает это, вызывая acf_esc_html для значения перед применением фильтра the_content, чтобы обработать любые встраивания в поле.
Когда ваш тип поля будет готов самостоятельно обрабатывать свой HTML, вы можете пометить его как совместимый, добавив 'escaping_html' => true в новое свойство класса supports:
$this->supports = array(
'escaping_html' => true,
);Обновлено: 01.06.2026