Функция wp_dropdown_users() в WordPress с примерами

Функция wp_dropdown_users() в WordPress используется для создания выпадающего списка всех зарегистрированных пользователей. Она возвращает или выводит HTML-код с элементами <option>, которые можно вставить в элемент <select>. Функция поддерживает большое количество аргументов для кастомизации списка пользователей, а также может работать с ролями, сортировкой, фильтрацией и другими параметрами.

wp_dropdown_users( array|string $args = '' ): string

Функция создаёт HTML-контент для выпадающего списка пользователей. По умолчанию список выводится на экран, но это можно изменить с помощью параметра 'echo'. Вы также можете включить или исключить конкретных пользователей с помощью аргументов 'include' и 'exclude'.

Параметры

• $args (массив|строка, необязательный) — Массив или строка с аргументами для генерации выпадающего списка пользователей. Ниже приведены основные аргументы:
  • show_option_all (string)
    Текст, который будет отображаться в качестве первого пункта в выпадающем списке для выбора всех пользователей.
    По умолчанию: ''.
  • show_option_none (string)
    Текст, который будет отображаться, если пользователи не найдены.
    По умолчанию: ''.
  • option_none_value (int|string)
    Значение, которое будет использовано для опции, если пользователи не найдены (соответствует show_option_none).
    По умолчанию: -1.
  • hide_if_only_one_author (string)
    Если установлено, функция не будет генерировать выпадающий список, если найден только один пользователь.
    По умолчанию: false.
  • orderby (string)
    Поле для сортировки пользователей. Принимает любые поля пользователя. Например: ID, user_nicename, display_name.
    По умолчанию: 'display_name'.
  • order (string)
    Направление сортировки. Может быть:
    • 'ASC' — по возрастанию.
    • 'DESC' — по убыванию.
      По умолчанию: 'ASC'.
  • include (int[]|string)
    Массив или строка с перечислением ID пользователей, которые должны быть включены в выпадающий список.
    По умолчанию: ''.
  • exclude (int[]|string)
    Массив или строка с перечислением ID пользователей, которые должны быть исключены из выпадающего списка.
    По умолчанию: ''.
  • multi (bool|int)
    Определяет, нужно ли пропускать атрибут id в элементе <select>.
    Принимает 1|true или 0|false.
    По умолчанию: 0|false.
  • show (string)
    Поле пользователя для отображения в списке. Если значение поля пусто, будет отображён user_login в скобках.
    Принимает любое поле пользователя или 'display_name_with_login' для отображения имени и логина в скобках.
    По умолчанию: 'display_name'.
  • echo (int|bool)
    Определяет, будет ли HTML код выводиться или возвращаться функцией.
    Принимает 1|true (выводить) или 0|false (вернуть).
    По умолчанию: 1|true.
  • selected (int)
    ID пользователя, который должен быть выбран по умолчанию.
    По умолчанию: 0.
  • include_selected (bool)
    Определяет, нужно ли всегда включать выбранного пользователя в выпадающий список, даже если он исключён через другие параметры.
    По умолчанию: false.
  • name (string)
    Атрибут name для элемента <select>.
    По умолчанию: 'user'.
  • id (string)
    Атрибут id для элемента <select>. По умолчанию совпадает с параметром 'name'.
    По умолчанию: значение параметра 'name'.
  • class (string)
    Атрибут class для элемента <select>.
    По умолчанию: ''.
  • blog_id (int)
    ID блога (используется только для мультисайтов).
    По умолчанию: ID текущего блога.
  • who (string)
    Устаревший параметр, используйте параметр capability вместо него.
    Указывает, каких пользователей запрашивать. Принимает:
    • '' — всех пользователей.
    • 'authors' — пользователей, которые могут публиковать посты.
      По умолчанию: ''.
  • role (string|string[])
    Строка или массив ролей пользователей, которые должны быть включены в результат. Пользователи должны соответствовать всем перечисленным ролям.
  • role__in (string[])
    Массив ролей, один из которых должен иметь пользователь, чтобы быть включённым в список.
    По умолчанию: [].
  • role__not_in (string[])
    Массив ролей, пользователи с которыми будут исключены из результата.
    По умолчанию: [].
  • capability (string|string[])
    Строка или массив с перечнем прав доступа (capabilities), которым должны соответствовать пользователи для включения в результат. Все перечисленные права должны быть у пользователя.
  • capability__in (string[])
    Массив с перечнем прав доступа, хотя бы одно из которых должно быть у пользователя для включения в результат.
    По умолчанию: [].
  • capability__not_in (string[])
    Массив с перечнем прав доступа, хотя бы одно из которых должно отсутствовать у пользователя для его исключения из результата.
    По умолчанию: [].

Возвращаемое значение

Возвращает строку с HTML-кодом выпадающего списка пользователей, если 'echo' => false. В противном случае HTML-код выводится напрямую.

Пример 1: Базовое использование функции

Этот пример создаёт выпадающий список всех зарегистрированных пользователей:

echo '<select name="user">';
    wp_dropdown_users();
echo '</select>';

Результат: создаётся список всех пользователей сайта с отображением их имени.

Пример 2: Выпадающий список с выбранным пользователем

Если вы хотите, чтобы определённый пользователь был выбран по умолчанию, можно передать его ID в параметре 'selected':

echo '<select name="user">';
    wp_dropdown_users( array( 'selected' => 2 ) );
echo '</select>';

В этом примере пользователь с ID 2 будет выбран в списке по умолчанию.

Пример 3: Создание формы с выпадающим списком пользователей и кнопкой отправки

Этот пример создаёт форму с выпадающим списком пользователей и кнопкой для отправки формы:

echo '<form action="' . esc_url( home_url() ) . '" method="get">';
    wp_dropdown_users( array( 'name' => 'author', 'show_option_all' => 'Все пользователи' ) );
    echo '<input type="submit" value="Посмотреть" />';
echo '</form>';

Результат: будет создана форма с выпадающим списком всех пользователей и кнопкой для отправки запроса.

Пример 4: Фильтрация по роли пользователя

Если необходимо отобразить только пользователей с определённой ролью, можно использовать параметр 'role'. Например, выведем только пользователей с ролью Editor:

wp_dropdown_users( array( 'role' => 'editor', 'show_option_all' => 'Все редакторы' ) );

Этот код создаст выпадающий список, в котором будут отображаться только пользователи с ролью Editor.

Пример 5: Исключение пользователей из списка

Для исключения определённых пользователей из списка используйте параметр 'exclude'. Например, исключим пользователей с ID 1 и 3:

wp_dropdown_users( array( 'exclude' => array( 1, 3 ) ) );

Этот код создаст выпадающий список всех пользователей, за исключением тех, чьи ID равны 1 и 3.

Пример 6: Возврат HTML без вывода

Если вы хотите получить HTML-код выпадающего списка в виде строки, а не выводить его сразу, используйте аргумент 'echo' => false:

$dropdown_html = wp_dropdown_users( array( 'echo' => false ) );
echo '<div class="dropdown-wrapper">' . $dropdown_html . '</div>';

Этот код сохранит HTML-код списка в переменной $dropdown_html, а затем выведет его внутри контейнера <div>.

Заключение

Функция wp_dropdown_users() — это мощный инструмент для создания выпадающих списков пользователей в WordPress. Она предоставляет множество опций для фильтрации, сортировки и кастомизации списка, что делает её полезной как для административных панелей, так и для пользовательских интерфейсов.