プラグインAdvanced custom fields(ACF)のacf/fields/taxonomy/wp_list_categoriesフィルタの使用方法・解説

概要

acf/fields/taxonomy/wp_list_categoriesは、Advanced Custom Fields (ACF) プラグインで使用されるフィルタであり、分類フィールド (リスト) 内の用語を照会するために使用される $args をフィルターします。このフィルタを利用することで、デフォルトのカテゴリーリストに独自のクエリオプションやカスタマイズを追加できます。以下のような機能でよく使われます：

特定のカテゴリーのみを表示する
カテゴリーリストのスタイルやCSSクラスを変更する
階層構造を持つカテゴリーの表示方法を調整する
カテゴリーの投稿数を表示/非表示にする
特定の投稿タイプに関連するカテゴリーのみをフィルタリングする
カスタム過去/未来の記事のカテゴリーを表示する

構文

add_filter('acf/fields/taxonomy/wp_list_categories', 'my_acf_wp_list_categories', 10, 2);

function my_acf_wp_list_categories($args, $field) {
    // カスタムロジック
    return $args;
}

パラメータ

$args: wp_list_categories() に渡される引数を含む連想配列。
$field: ACF フィールド情報を含む配列。

戻り値

フィルターされた $args の連想配列。

使用可能なバージョン

ACF バージョン: 5.0 以降
WordPress バージョン: 4.0 以降

サンプルコード

サンプルコード1: 特定のカテゴリーのみを表示する

add_filter('acf/fields/taxonomy/wp_list_categories', 'filter_specific_categories', 10, 2);

function filter_specific_categories($args, $field) {
    $args['include'] = '1,2,3'; // カテゴリーID 1, 2, 3を表示
    return $args;
}

このサンプルコードは、特定のカテゴリーIDのみを表示するために $args['include'] をフィルタリングしています。これにより、指定されたカテゴリーだけがリストに含まれます。

サンプルコード2: 表示するカテゴリーのスタイルを変更する

add_filter('acf/fields/taxonomy/wp_list_categories', 'custom_category_styles', 10, 2);

function custom_category_styles($args, $field) {
    $args['style'] = 'list'; // 表示スタイルをリストに設定
    return $args;
}

このサンプルコードは、カテゴリーリストをリストスタイルとして表示する設定を $args に追加しています。これにより、HTMLの出力が変更されます。

サンプルコード3: カテゴリーの投稿数を非表示にする

add_filter('acf/fields/taxonomy/wp_list_categories', 'hide_category_post_count', 10, 2);

function hide_category_post_count($args, $field) {
    $args['show_count'] = false; // 投稿数を非表示
    return $args;
}

このサンプルコードは、カテゴリーリスト内での投稿数の表示をオフにしています。これにより、よりシンプルな表示になります。

サンプルコード4: 階層構造の調整

add_filter('acf/fields/taxonomy/wp_list_categories', 'custom_hierarchy_settings', 10, 2);

function custom_hierarchy_settings($args, $field) {
    $args['hierarchical'] = true; // 階層的な表示を有効にする
    return $args;
}

このサンプルコードは、カテゴリーを階層的に表示するために $args に hierarchical オプションを追加しています。これにより、親子関係が保持されて表示されます。

サンプルコード5: カスタム投稿タイプのカテゴリーをフィルタリング

add_filter('acf/fields/taxonomy/wp_list_categories', 'filter_custom_post_type_categories', 10, 2);

function filter_custom_post_type_categories($args, $field) {
    $args['taxonomy'] = 'custom_taxonomy'; // カスタムタクソノミーを指定
    return $args;
}

このサンプルコードでは、特定のカスタム投稿タイプに関連するカテゴリーのみを表示するために $args['taxonomy'] を変更しています。

この関数のアクションでの使用可能性

アクション	使用可能性
mu_plugin_loaded
registered_post_type
plugins_loaded
wp_roles_init
setup_theme
after_setup_theme
set_current_user
init
register_sidebar
wp_loaded
send_headers
parse_query
pre_get_posts
wp
template_redirect
get_header
wp_head

概要

構文