## Функция ADD_SETTINGS_FIELD() │ WP 2.7.0
### Добавление нового поля в настройки
Функция add_settings_field() является частью API настроек в WordPress. Она позволяет вам добавлять новое поле в секцию на странице настроек. Эти поля отображаются с помощью функции do_settings_fields() внутри do_settings_sections().
Параметр $callback должен содержать имя функции, которая выводит HTML-коды для этого поля настроек. Вы можете использовать функцию get_option(), чтобы получить существующие значения для отображения.
**Важно:** В этой функции нет хуков.
### Возвращаемое значение
Функция ничего не возвращает (null).
### Использование
Для добавления поля в настройки, используйте следующую структуру:
```php
add_settings_field( $id, $title, $callback, $page, $section, $args );Параметры:
$id(string, обязательный) — уникальное имя для идентификации поля. Используется в атрибуте 'id' HTML-тегов.$title(string, обязательный) — форматированный заголовок поля. Появляется в качестве метки для поля при выводе.$callback(callable, обязательный) — функция, которая заполняет поле нужными элементами формы. Функция должна выводить свой результат.$page(string, обязательный) — slug (идентификатор) страницы настроек, на которой будет отображаться поле (например,general,reading,writingи т.д.).$section(string, необязательный) — slug (идентификатор) секции на странице настроек, где будет отображаться поле. По умолчанию — 'default'.$args(array, необязательный) — дополнительные аргументы, которые передаются в функцию обратного вызова. По умолчанию — пустой массив.
Примеры дополнительных аргументов:
label_for(string) — когда предоставлено, заголовок настройки будет обернут в элемент<label>, его атрибутforбудет заполнен этим значением.class(string) — CSS класс, который будет добавлен к элементу<tr>, когда поле будет выведено.
Примеры использования
Пример 1: Добавление нового поля на страницу основных настроек WordPress
add_action( 'admin_menu', 'add_option_field_to_general_admin_page' );
function add_option_field_to_general_admin_page() {
$option_name = 'my_option';
// Регистрация опции
register_setting( 'general', $option_name );
// Добавление поля
add_settings_field(
'myprefix_setting-id',
'Название опции',
'myprefix_setting_callback_function',
'general',
'default',
[
'id' => 'myprefix_setting-id',
'option_name' => 'my_option'
]
);
}
function myprefix_setting_callback_function( $val ) {
$id = $val['id'];
$option_name = $val['option_name'];
?>
Как результат, на странице "Общие" в самом низу мы получим новое полностью работающее поле опции.
Пример 2: Использование классов в OOP
class ClassName {
public function __construct() {
add_action( 'admin_init', [ $this, 'your_function' ] );
}
function your_function() {
add_settings_field(
'myprefix_setting-id',
'Это заголовок настройки',
[ $this, 'myprefix_setting_callback_function' ],
'general',
'default',
[ 'label_for' => 'myprefix_setting-id' ]
);
}
function myprefix_setting_callback_function( $args ) {
echo 'Содержимое здесь';
}
}
$ClassName = new ClassName();Пример 3: Поле настройки с чекбоксом
Чекбокс можно проверить на фронтенде, просто проверив его с помощью isset. Нет необходимости добавлять дополнительные проверки, такие как 1, 0, true или false — если чекбокс не установлен, то он возвращает false.
add_action( 'admin_menu', 'add_option_field_to_general_admin_page' );
function add_option_field_to_general_admin_page() {
add_settings_field(
'wpdevref_removestyles_field',
esc_attr__( 'Убрать стили плагина', 'wpdevref' ),
'wpdevref_removestyles_field_cb',
'general',
'default',
[
'type' => 'checkbox',
'option_group' => 'wpdevref_options',
'name' => 'wpdevref_removestyles_field',
'label_for' => 'wpdevref_removestyles_field',
'value' => (int) ( get_option( 'wpdevref_options' )['wpdevref_removestyles_field'] ?? 0 ),
'description' => __( 'Отметьте, чтобы удалить заранее установленные стили плагина.', 'wpdevref' ),
'checked' => get_option( 'wpdevref_options' )['wpdevref_removestyles_field'] ?? 0,
'tip' => esc_attr__( 'Используйте, если поля плагина сильно изменились при установке этого плагина.', 'wpdevref' ),
]
);
}
function wpdevref_removestyles_field_cb( $args ) {
$options = get_option( $args['option_group'] );
$value = $options[ $args['name'] ] ?? null;
$html = '
';
$html = strtr( $html, [
'{TIP}' => esc_attr( $args['tip'] ),
'{ID}' => esc_attr( $args['name'] ),
'{NAME}' => esc_attr( $args['option_group'] . "[{$args['name']}]" ),
'{CHECKED}' => $value ? ' checked="checked" ' : '',
'{DESCRIPTION}' => esc_html( $args['description'] ),
] );
echo $html;
}После этого можно получить значение опции следующим образом:
$options = get_option( 'wpdevref_options' );
$value = $options['wpdevref_removestyles_field'] ?? '';
if( ! $value ){
// Выполнить некоторые действия
}Примечания
- Глобальный массив
$wp_settings_fieldsсодержит информацию о полях настроек и их страницах/сектах.
Изменения
- С версии 2.7.0 — функция была введена.
- С версии 4.2.0 — добавлен параметр
$class.