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

概要

フィルタ acf/fields/taxonomy/query は、Advanced Custom Fields (ACF) プラグインを使用して作成された分類フィールド（ドロップダウン）の選択肢をカスタマイズするために利用されます。このフィルタは、分類用語を表示する際に用いるクエリの引数を変更することができ、特定の条件に基づいた用語のリストを作成する場合に便利です。具体的には、特定の用語を除外したり、特定のタクソノミーの用語だけを表示するための条件を追加したりするのに使われます。

よく使われる機能としては、以下のようなものがあります：
1. 特定の親用語を持つすべての子用語を取得する。
2. 特定の条件に基づいて用語をフィルタリングする。
3. カスタムタクソノミーのみに絞ったリストを表示する。
4. 不要な用語を結果から除外する。
5. 並び替えや検索機能を強化する。
6. 参加するユーザーによって異なる用語を動的に表示する。

構文

add_filter('acf/fields/taxonomy/query', 'my_acf_taxonomy_query', 10, 3);

パラメータ

$args : WP_Term_Query の引数として渡される配列。
$field : フィールドのメタデータ。
$post_id : 現在の投稿の ID。

戻り値

フィルタを適用した後の $args 配列が返されます。

ACF と WP のバージョン

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

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

アクション	使用可能性
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

サンプルコード

サンプルコード1: 特定のタクソノミーのみを表示

add_filter('acf/fields/taxonomy/query', 'my_custom_taxonomy_query', 10, 3);
function my_custom_taxonomy_query($args, $field, $post_id) {
    $args['taxonomy'] = 'my_custom_taxonomy';
    return $args;
}

このサンプルは、特定のカスタムタクソノミー（my_custom_taxonomy）の用語のみを表示するために $args をフィルターしています。

サンプルコード2: 特定の用語を除外

add_filter('acf/fields/taxonomy/query', 'my_exclude_terms', 10, 3);
function my_exclude_terms($args, $field, $post_id) {
    $args['exclude'] = array(1, 2); // ID 1と2の用語を除外
    return $args;
}

このサンプルは、指定した用語ID（1と2）を結果から除外します。

サンプルコード3: 親用語を指定する

add_filter('acf/fields/taxonomy/query', 'my_parent_term', 10, 3);
function my_parent_term($args, $field, $post_id) {
    $args['parent'] = 3; // 親用語のIDが3の用語を取得
    return $args;
}

このコードは、特定の親用語（親用語のIDが3）の子用語のみを取得するように $args を修正します。

サンプルコード4: タクソノミーの順序を変更

add_filter('acf/fields/taxonomy/query', 'my_order_terms', 10, 3);
function my_order_terms($args, $field, $post_id) {
    $args['orderby'] = 'name'; // 用語名でソート
    $args['order'] = 'ASC'; // 昇順
    return $args;
}

このサンプルは、用語を名前（name）で昇順にソートするよう $args を変更します。

サンプルコード5: 現在のユーザーのフィルタを適用

add_filter('acf/fields/taxonomy/query', 'my_user_based_terms', 10, 3);
function my_user_based_terms($args, $field, $post_id) {
    if (current_user_can('editor')) {
        $args['slug'] = 'editor_term'; // エディタユーザーに特定の用語を表示
    }
    return $args;
}

このコードは、現在のユーザーがエディタであれば、特定の用語（slugがeditor_term）のみを表示するように $args を変更します。

引用元のページ:
1. https://www.advancedcustomfields.com/resources/acf-fields/taxonomy/
2. https://www.advancedcustomfields.com/resources/acf-fields/taxonomy/query/
3. https://www.advancedcustomfields.com/resources/acf-fields/taxonomy/#filtering
4. https://www.advancedcustomfields.com/resources/acf-fields/taxonomy/#customizing
5. https://www.advancedcustomfields.com/resources/acf-fields/taxonomy/#example

概要

構文