# wp_terms_checklist()

URL: https://chugunov.pro/api-wordpress/functions/wp_terms_checklist/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 4.4.0.

## Сигнатура

```php
wp_terms_checklist( int $post_id, array|string $args = array() ): string
```

## Описание

Версия wp_category_checklist(), не зависящая от таксономии.

## Параметры

- `$post_id` `int` — необязательный. ID записи. Значение по умолчанию 0.
- `$args` `array|string` — необязательный, по умолчанию `array()`. Массив или строка аргументов для генерации списка терминов с флажками.
  
  descendants_and_self intID категории, которую нужно вывести вместе с её потомками.
  
  Значение по умолчанию 0.
  
  selected_cats int[]Массив ID категорий, которые нужно отметить как выбранные. Значение по умолчанию false.
  
  popular_cats int[]Массив ID категорий, которым присваивается класс "popular-category".
  
  Значение по умолчанию false.
  
  walker WalkerОбъект Walker для построения вывода. По умолчанию пустой, что приводит к использованию экземпляра Walker_Category_Checklist.
  
  taxonomy stringТаксономия, для которой генерируется список. Значение по умолчанию 'category'.
  
  checked_ontop boolПеремещать ли отмеченные элементы из иерархии в начало списка. Значение по умолчанию true.
  
  echo boolВыводить ли сгенерированную разметку. False — вернуть разметку вместо её вывода. Значение по умолчанию true.

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

`string`

## Исходный код

Файл: `wp-admin/includes/template.php:81`

```php
function wp_terms_checklist( $post_id = 0, $args = array() ) {
	$defaults = array(
		'descendants_and_self' => 0,
		'selected_cats'        => false,
		'popular_cats'         => false,
		'walker'               => null,
		'taxonomy'             => 'category',
		'checked_ontop'        => true,
		'echo'                 => true,
	);

	/**
	 * Filters the taxonomy terms checklist arguments.
	 *
	 * @since 3.4.0
	 *
	 * @see wp_terms_checklist()
	 *
	 * @param array|string $args    An array or string of arguments.
	 * @param int          $post_id The post ID.
	 */
	$params = apply_filters( 'wp_terms_checklist_args', $args, $post_id );

	$parsed_args = wp_parse_args( $params, $defaults );

	if ( empty( $parsed_args['walker'] ) || ! ( $parsed_args['walker'] instanceof Walker ) ) {
		$walker = new Walker_Category_Checklist();
	} else {
		$walker = $parsed_args['walker'];
	}

	$taxonomy             = $parsed_args['taxonomy'];
	$descendants_and_self = (int) $parsed_args['descendants_and_self'];

	$args = array( 'taxonomy' => $taxonomy );

	$tax              = get_taxonomy( $taxonomy );
	$args['disabled'] = ! current_user_can( $tax->cap->assign_terms );

	$args['list_only'] = ! empty( $parsed_args['list_only'] );

	if ( is_array( $parsed_args['selected_cats'] ) ) {
		$args['selected_cats'] = array_map( 'intval', $parsed_args['selected_cats'] );
	} elseif ( $post_id ) {
		$args['selected_cats'] = wp_get_object_terms( $post_id, $taxonomy, array_merge( $args, array( 'fields' => 'ids' ) ) );
	} else {
		$args['selected_cats'] = array();
	}

	if ( is_array( $parsed_args['popular_cats'] ) ) {
		$args['popular_cats'] = array_map( 'intval', $parsed_args['popular_cats'] );
	} else {
		$args['popular_cats'] = get_terms(
			array(
				'taxonomy'     => $taxonomy,
				'fields'       => 'ids',
				'orderby'      => 'count',
				'order'        => 'DESC',
				'number'       => 10,
				'hierarchical' => false,
			)
		);
	}

	if ( $descendants_and_self ) {
		$categories = (array) get_terms(
			array(
				'taxonomy'     => $taxonomy,
				'child_of'     => $descendants_and_self,
				'hierarchical' => 0,
				'hide_empty'   => 0,
			)
		);
		$self       = get_term( $descendants_and_self, $taxonomy );
		array_unshift( $categories, $self );
	} else {
		$categories = (array) get_terms(
			array(
				'taxonomy' => $taxonomy,
				'get'      => 'all',
			)
		);
	}

	$output = '';

	if ( $parsed_args['checked_ontop'] ) {
		/*
		 * Post-process $categories rather than adding an exclude to the get_terms() query
		 * to keep the query the same across all posts (for any query cache).
		 */
		$checked_categories = array();
		$keys               = array_keys( $categories );

		foreach ( $keys as $k ) {
			if ( in_array( $categories[ $k ]->term_id, $args['selected_cats'], true ) ) {
				$checked_categories[] = $categories[ $k ];
				unset( $categories[ $k ] );
			}
		}

		// Put checked categories on top.
		$output .= $walker->walk( $checked_categories, 0, $args );
	}
	// Then the rest of them.
	$output .= $walker->walk( $categories, 0, $args );

	if ( $parsed_args['echo'] ) {
		echo $output;
	}

	return $output;
}
```

## История изменений

- 4.4.0 — Introduced the $echo argument.
- 3.0.0 — Introduced.

## Связанные

Использует: `Walker::walk`, [`wp_get_object_terms`](https://chugunov.pro/api-wordpress/functions/wp_get_object_terms/), [`get_terms`](https://chugunov.pro/api-wordpress/functions/get_terms/), [`current_user_can`](https://chugunov.pro/api-wordpress/functions/current_user_can/), [`wp_parse_args`](https://chugunov.pro/api-wordpress/functions/wp_parse_args/), [`get_taxonomy`](https://chugunov.pro/api-wordpress/functions/get_taxonomy/), [`get_term`](https://chugunov.pro/api-wordpress/functions/get_term/), [`apply_filters`](https://chugunov.pro/api-wordpress/functions/apply_filters/).
Используется в: [`wp_category_checklist`](https://chugunov.pro/api-wordpress/functions/wp_category_checklist/), [`_wp_ajax_add_hierarchical_term`](https://chugunov.pro/api-wordpress/functions/_wp_ajax_add_hierarchical_term/), [`post_categories_meta_box`](https://chugunov.pro/api-wordpress/functions/post_categories_meta_box/), `WP_Posts_List_Table::inline_edit`.

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/wp_terms_checklist/