函数描述
显示一个目录下拉选择表单元素。
使用方法
wp_dropdown_categories( $args );默认使用
$args = [
'show_option_all' => '',
'show_option_none' => '',
'option_none_value' => '-1',
'orderby' => 'ID',
'order' => 'ASC',
'show_count' => 0,
'hide_empty' => 1,
'child_of' => 0,
'exclude' => '',
'echo' => 1,
'selected' => 0,
'hierarchical' => 0,
'name' => 'cat',
'id' => '',
'class' => 'postform',
'depth' => 0,
'tab_index' => 0,
'taxonomy' => 'category',
'hide_if_empty' => false,
'value_field' => 'term_id',
];默认情况下，以上代码显示方法为：
- 按分类id升序排列
- 不显示分类中的文章数量
- 不显示没有文章的分类目录
- 不排除任何分类目录
- 直接显示（echo）分类目录
- 表单中没有选中任何分类目录
- 不以分级结构显示分类目录
- 分类 ‘cat’ 为下拉选择的表单名称
- 分类表单css类 ‘postform’
- 没有深度限制No depth limit
- Tab index 为 0
- 使用的分类方法为 category
- 如果没有分类项目隐藏下拉选择
- 分局选择的分类项目输出分类id
参数
| 参数 | 数据类型 | 是否必需 | 描述 | 默认值 |
|---|---|---|---|---|
| $args | 字符串｜数组 | 是 | 覆盖默认参数的数组或查询字符串 | 空 |
返回值
字符串，除非 ‘echo’ 参数设置为0，函数将直接显示 HTML 内容。
数组参数
| 参数 | 数据类型 | 描述 | 默认值 |
|---|---|---|---|
| show_option_all | 字符串 | 显示 ‘所有分类目录’ 选项的文本，下拉选项默认显示为 ‘所有分类目录 | |
| show_option_none | 字符串 | 在下拉选择表单的顶部创建一个附加的<option>选项，以便不选择任何分类时使用。 | |
| option_none_value | 字符串 | 选择分类的选项值 | -1 |
| orderby | 字符串 | 用来给分类排序的数据列名称，可用的值为 ‘ID’, ‘name’ 与 ‘slug’ | ID |
| order | 字符串 | 分类的排序方式，可用的值为 ‘ASC’ 和 ‘DESC’ | ASC |
| pad_counts | 布尔值 | 有关参数说明，请参见get_terms() | false |
| show_count | 布尔值｜整数 | 是否包含分类中的文章数量，接受的值为0、1或对应的布尔值 | 0 |
| echo | 布尔值｜整数 | 直接显示或返回生成的HTML，接受的值为0、1或对应的布尔值 | 0 |
| hierarchical | 布尔值｜整数 | 是否显示为分层结构，接受的值为0、1或对应的布尔值 | 0 |
| depth | 整数 | 最大深度 | 0 |
| tab_index | 整数 | 选择元素的制表符索引顺序 | 0 |
| name | 字符串 | 选择元素的「name」属性 | cat |
| id | 字符串 | 选择元素的「id」属性 | cat |
| class | 字符串 | 选择元素的「class」属性 | postform |
| selected | 整数｜字符串 | 默认选择中选项 | 0 |
| value_field | 字符串 | 用于填充选项的分类字段，可以值有：’term_id’, ‘name’, ‘slug’, ‘term_group’, ‘term_taxonomy_id’, ‘taxonomy’, ‘description’, ‘parent’, ‘count’。 | term_id |
| taxonomy | 字符串 | 获取数据的分类法名称 | category |
| hide_if_empty | 布尔值 | 没有数据时，是否隐藏选择元素 | false |
| required | 布尔值 | 是否包含HTML5的「require」属性 | false |
使用示例
带提交按钮的下拉表单
显示一个有提交按钮的页面选择下拉表单，下拉表单中表现页面的层次关系。
<li id="categories">
<h2><?php _e( '分类目录:' ); ?></h2>
<form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">
<?php wp_dropdown_categories( 'show_count=1&hierarchical=1' ); ?>
<input type="submit" name="submit" value="view" />
</form>
</li>
使用 JavaScript 而不是提交按钮提交下拉表单
下面的代码将显示一个分类下拉表单，选择某个分类时，页面将跳转到这个分类存档页面。
<li id="categories"><h2><?php _e( '按分类过滤' ); ?></h2>
<?php wp_dropdown_categories( 'show_option_none=选择分类' ); ?>
<script type="text/javascript">
<!--
var dropdown = document.getElementById("cat");
function onCatChange() {
if ( dropdown.options[dropdown.selectedIndex].value > 0 ) {
location.href = "<?php echo esc_url( home_url( '/' ) ); ?>?cat="+dropdown.options[dropdown.selectedIndex].value;
}
}
dropdown.onchange = onCatChange;
-->
</script>
</li>
使用 JavaScript 而不是提交按钮提交下拉表单（2）
此示例中使用了显示参数 (echo=0) ，在Javascript代码中插入了简单的 preg_replace。这样，即使浏览器不支持JavaScript，下拉表单也能退回到标准的HTML表单显示。
<li id="categories">
<h2><?php _e('按分类过滤'); ?></h2>
<form id="category-select" class="category-select" action="<?php echo esc_url(home_url('/')); ?>" method="get">
<?php
$args = [
'show_option_none' => __('选择分类'),
'show_count' => 1,
'orderby' => 'name',
'echo' => 0,
];
$select = wp_dropdown_categories($args);
$replace = "<select$1 onchange='return this.form.submit()'>";
$select = preg_replace('#<select([^>]*)>#', $replace, $select);
echo $select;
?>
<noscript>
<input type="submit" value="View" />
</noscript>
</form>
</li>故障排除
下拉选项为空
默认情况下，wp_dropdown_categories 将返回至少有一篇文章的分类，如果你想覆盖此设置，可以设置 hide_empty 参数为 false (“0”)。
示例：
<?php wp_dropdown_categories( 'hide_empty=0' ); ?>