関数リファレンス/register taxonomy

説明

この関数はタクソノミーを (カスタム分類として) 追加したり、上書きしたりします。タクソノミーの名前、対象とするオブジェクトの名前、それから引数の配列をパラメータとします。何も値を返しません。

タクソノミーの名前は注意深く選んで、他のタクソノミーや投稿、それから WordPress の public/private クエリ変数と衝突しないようにします。このページにある予約語セクションでチェックしてください。特に大文字は禁止です（バージョン 3.0 では許されていましたが、バージョン 3.1 からは "Cheatin'" エラーが出ます）。

使い方

<?php register_taxonomy( $taxonomy, $object_type, $args ); ?>

この関数は init アクションを使って呼び出してください。 アクションの外から呼び出すとトラブルの元になります。詳しくはチケット #15568 を参照してください。

カスタム投稿タイプにカスタムタクソノミー（カスタム分類）を登録するときは安全第一を心がけてください。この関数でタクソノミーとオブジェクトを繋いだ後、すぐに register_taxonomy_for_object_type() を呼び出してください。これを怠ると、parse_request や pre_get_posts の中でフィルター呼び出しが行われるときに投稿タイプが不明になってしまい、どんな結果になるかわかりません。

パラメータ

$taxonomy

（文字列）（必須）タクソノミーの名前。英小文字とアンダースコアのみ、32文字以下（データベース構造による制限）。

初期値：なし

$object_type

（配列/文字列）（必須）タクソノミーオブジェクトのオブジェクト名。オブジェクトタイプは WordPress 標準の投稿タイプ、または登録されているカスタム投稿タイプ。

初期値：なし

標準の投稿タイプ：

post
page
attachment
revision
nav_menu_item

カスタム投稿タイプ：

{custom_post_type} - カスタム投稿タイプの名前は英小文字とし、空白は禁止です。
null - 明示的に null をセットすると、タクソノミーは登録されますがどのオブジェクトにも関連付けられないため、管理画面から直接使うことはできません。その場合、カスタム投稿タイプを登録するときに 'taxonomy' パラメータを使うか（ $args に入れて渡す。register_post_type() を参照）、それとも register_taxonomy_for_object_type() を使って改めて登録する必要があります。

$args

（配列/文字列）（オプション）引数の配列

初期値：なし

引数

label

（文字列）（オプション）タクソノミーの複数形の名前。翻訳の対象。

初期値： $labels->name で上書きされる。

labels

（配列）（オプション）タクソノミーに付けるラベルの配列。デフォルトでは、階層のないタクソノミーにはタグのラベルが、階層化したタクソノミーにはカテゴリーのラベルが使われます。

初期値：空（指定しない）の場合、label の値が name に入り、name の値が singular_name に入る。

'name' - タクソノミーの一般的な名前（普通は複数形）。 $tax->label によって上書きされて同じになる。デフォルトは _x( 'Post Tags', 'taxonomy general name' ) または _x( 'Categories', 'taxonomy general name' ) 。この文字列を国際化するときは、gettext context を使用してカスタム投稿タイプに合わせてください。例： _x('Writers', 'taxonomy general name');
'singular_name' - タクソノミーのオブジェクト 1 個の名前（単数形）。デフォルトは _x( 'Post Tag', 'taxonomy singular name' ) または _x( 'Category', 'taxonomy singular name' ) 。この文字列を国際化するときは、gettext context を使用してカスタム投稿タイプに合わせてください。例： _x('Writer', 'taxonomy singular name');
'menu_name' - メニュー名の文字列。メニュー項目の名前になります。無指定の場合、デフォルトで name のラベルが入ります。
'all_items' - 「すべての項目」の文字列。デフォルトは __( 'All Tags' ) または __( 'All Categories' )
'edit_item' - 「項目を編集」の文字列。デフォルトは __( 'Edit Tag' ) または __( 'Edit Category' )
'view_item' - 「項目を表示」の文字列。デフォルトは __( 'View Tag' ) または __( 'View Category' )
'update_item' - 「項目を更新」の文字列。デフォルトは __( 'Update Tag' ) または __( 'Update Category' )
'add_new_item' - 「新しい項目を追加」の文字列。デフォルトは __( 'Add New Tag' ) または __( 'Add New Category' )
'new_item_name' - 「新しい項目の名前」の文字列。デフォルトは __( 'New Tag Name' ) または __( 'New Category Name' )
'parent_item' - 「親の項目」の文字列。これは投稿のタグのような階層化しないタクソノミーには使われません。デフォルトは null または __( 'Parent Category' )
'parent_item_colon' - parent_item と同じ文字列の後ろにコロン : を付けたもの。デフォルトは null または __( 'Parent Category:' )
'search_items' - 「項目を検索」の文字列。デフォルトは __( 'Search Tags' ) または __( 'Search Categories' )
'popular_items' - 「人気の項目」の文字列。階層のあるタクソノミーには使われません。デフォルトは __( 'Popular Tags' ) または null
'separate_items_with_commas' - タクソノミーのメタボックスで使われる「項目をコンマで区切ってください」の文字列。階層のあるタクソノミーには使われません。デフォルトは __( 'Separate tags with commas' ) または null
'add_or_remove_items' - JavaScript が無効なときにメタボックスで使われる「項目の追加または削除」の文字列。階層のあるタクソノミーには使われません。デフォルトは __( 'Add or remove tags' ) または null
'choose_from_most_used' - タクソノミーのメタボックスで使われる「よく使われている項目から選択」の文字列。階層のあるタクソノミーには使われません。デフォルトは __( 'Choose from the most used tags' ) または null
'not_found' (バージョン 3.6 以降) - 項目が一つもないときにタクソノミーのメタボックスで「よく使われている項目から選択」をクリックすると表示される文字列。階層のあるタクソノミーには使われません。また、 (バージョン4.2以降) - カスタム分類のための項目がない場合には、これらの分類の一覧表で使用されるテキスト。デフォルトは__( 'No tags found.' ) または __( 'No categories found.' )

public

（真偽値）（オプション） true にすると、タクソノミーは（パブリックに）検索可能になります。

初期値： true

show_ui

（真偽値）（オプション） true にすると、タクソノミーを管理するためにデフォルトの UI を用意します。

初期値：無指定の場合、デフォルトで public 引数の値が入ります。バージョン 3.5 以降は、「添付」のタクソノミーについてこれを false にすると UI を隠します。

show_in_nav_menus

（真偽値）（オプション） true にすると、ナビゲーションメニューでこのタクソノミーを選択できます。

初期値：無指定の場合、デフォルトで public 引数の値が入ります。

show_tagcloud

（真偽値）（オプション） true にすると、タグクラウドのウィジェットがこのタクソノミーを使います。

初期値：無指定の場合、デフォルトで show_ui 引数の値が入ります。

show_in_quick_edit

（真偽値）（オプション）直接編集画面で、カスタム分類を表示するか。 ( バージョン4.2以降で使用可能)

初期値：無指定の場合、デフォルトは show_ui 引数の値。

meta_box_cb

（callback）（オプション）メタボックスを表示するためのコールバック関数を指定できます。（バージョン 3.8 以降で利用可能）

初期値： null

参考： デフォルトは、階層のあるタクソノミーならカテゴリー用メタボックス（ meta-boxes.php にある post_categories_meta_box() ）、階層化しないタクソノミーならタグ用メタボックス（ post_tags_meta_box() ）になります。false を指定するとメタボックスを表示しません。

show_admin_column

（真偽値）（オプション） true にすると、関連付けられた投稿タイプのテーブルにタクソノミーのカラムを自動生成します。（バージョン 3.5 以降で利用可能）

初期値： false

description

（文字列）（オプション）タクソノミーの説明が含まれています。

初期値： ""

hierarchical

（真偽値）（オプション） true ならカテゴリーのような階層あり（子を持つ）タクソノミー、false ならタグのような階層化しないタクソノミー。

初期値： false

参考： 階層のあるタクソノミーの場合、投稿の編集ページにあるタクソノミー管理ボックスに、既存カテゴリーを選択できるチェックボックス付きリストを表示します（デフォルトの投稿カテゴリーのように）。階層化しないタクソノミーの場合、投稿に付けるタクソノミーのタームをタイプ入力するための空のテキストフィールドだけを表示します（デフォルトの投稿タグのように）。

update_count_callback

（文字列）（オプション）関連付けられた $object_type（例えば投稿）の個数が更新された時に呼び出される関数の名前。フックによく似た動作になります。

初期値：ありませんが、下記の「参考」を見てください。

参考： デフォルトは '' です。この場合、wp_update_term_count_now() の中でカウントを実際に更新するとき、次のような動作になります。もしタクソノミーが post タイプだけに付けられているなら（user のような他の WordPress オブジェクトではなく）、組み込みの _update_post_term_count() 関数を使って、タームに関連付けられた公開済み投稿だけをカウントします。そうでなければ _update_generic_term_count() を使って、そのようなチェックを行わずにカウントします。

これは添付の場合に違いがはっきりします。添付は post の一種であるため、デフォルトの _update_post_term_count() が使われます。しかし、他の投稿へ実際に付けられた（画像を投稿へ挿入したような）添付だけがカウントされるため、これはおそらく期待外れでしょう。つまり、メディアライブラリーを使って WordPress へアップロードしてあっても、投稿へ付けていない添付はカウントされません。もし、あなたが添付にタクソノミーを付ける理由が、メディアライブラリーをドキュメント管理ソリューションのように使おうというのなら、投稿に付けられたものだけでなく付けられていないメディア項目もカウントしたいでしょう。その場合、update_count_callback の値に '_update_generic_term_count' を指定すれば、_update_generic_term_count() の使用を強制できます。

query_var

（真偽値または文字列）（オプション） false にすると query_var を無効化します。文字列を指定すると、デフォルトの $taxonomy（タクソノミーの「名前」）の代わりに、それがカスタム query_var になります。

初期値： $taxonomy

参考： query_var は、new WP_Query(array('people'=>$person_name)) のような WP_Query による直接クエリと、/?people=$person_name のような URL クエリに使われます。query_var を false にすると何れの方法も使えなくなりますが、それでも WP_Query(array('taxonomy'=>'people', 'term'=>$person_name)) のようにタクソノミーを直接指定したクエリで投稿を取得できます。

rewrite

（真偽値/配列）（オプション） false にすると、自動 URL 書き換え（俗にいう「pretty パーマリンク」）を回避できます。$args のように配列を指定すると、デフォルトのパーマリンクの URL 設定を下記のように変更できます。

初期値： true

'slug' - pretty パーマリンクの文字列として使用（例えば /tag/ ） - デフォルトは $taxonomy（タクソノミーの名前、すなわちスラッグ）
'with_front' - true にするとパーマリンクの前に front ベースを入れる - デフォルトは true
'hierarchical' - true にすると階層化した URL を使用可能にする（バージョン 3.1 で実装された） - デフォルトは false
'ep_mask' - （prettyパーマリンクの場合は必須）このタクソノミーにエンドポイントマスクを割り当てる - デフォルトは EP_NONE. EP_MASKを指定しない場合は、prettyパーマリンクは機能しません。詳しくは this Make WordPress Plugins summary of endpointsを参照。

参考： この変更を行った後、書き換えルールをフラッシュする必要があるかもしれません。一つの方法は「パーマリンク設定」ページを開いてルールを再保存します（変更する必要はありません）。もう一つの方法は $wp_rewrite->flush_rules() を呼び出します。ルールのフラッシュはタクソノミーを作成した後の一回だけ行ってください。プラグインやテーマを読み込む度に毎回行うのではありません。

capabilities

（配列）（オプション）このタクソノミーに関する権限の配列。

初期値：なし

'manage_terms' - 'manage_categories'
'edit_terms' - 'manage_categories'
'delete_terms' - 'manage_categories'
'assign_terms' - 'edit_posts'

sort

（真偽値）（オプション） true にすると、タクソノミーのタームがオブジェクトへ付けられた順序を記憶する。

初期値：なし

_builtin

（真偽値）（not for general use） true なら、このタクソノミーはネイティブ、つまり「組み込み」タクソノミーである。参考：この Codex エントリーは記録のために用意した - WordPress のコア開発者は、あなたが自分のタクソノミー（カスタム分類）を登録するときにこの引数を使わないようお願いする

初期値： false

例

以下は "book" というカスタム投稿タイプに "genres (ジャンル)" と "writers (著者)" というカスタム分類を追加する例です。バージョン 3.1 以降のみの引数を使っています。

参考：テーマの functions.php テンプレートファイル内でカスタム分類を定義できます：

<?php
// init アクションにフックして、そのタイミングで create_book_taxonomies を呼び出す
add_action( 'init', 'create_book_taxonomies', 0 );

// "book" カスタム投稿タイプに対して genres と writers という2つのカスタム分類を作成する
function create_book_taxonomies() {
	// （カテゴリーのような）階層化したカスタム分類を新たに追加
	$labels = array(
		'name'              => _x( 'Genres', 'taxonomy general name' ),
		'singular_name'     => _x( 'Genre', 'taxonomy singular name' ),
		'search_items'      => __( 'Search Genres' ),
		'all_items'         => __( 'All Genres' ),
		'parent_item'       => __( 'Parent Genre' ),
		'parent_item_colon' => __( 'Parent Genre:' ),
		'edit_item'         => __( 'Edit Genre' ),
		'update_item'       => __( 'Update Genre' ),
		'add_new_item'      => __( 'Add New Genre' ),
		'new_item_name'     => __( 'New Genre Name' ),
		'menu_name'         => __( 'Genre' ),
	);

	$args = array(
		'hierarchical'      => true,
		'labels'            => $labels,
		'show_ui'           => true,
		'show_admin_column' => true,
		'query_var'         => true,
		'rewrite'           => array( 'slug' => 'genre' ),
	);

	register_taxonomy( 'genre', array( 'book' ), $args );

	// （タグのような）階層のないカスタム分類を新たに追加
	$labels = array(
		'name'                       => _x( 'Writers', 'taxonomy general name' ),
		'singular_name'              => _x( 'Writer', 'taxonomy singular name' ),
		'search_items'               => __( 'Search Writers' ),
		'popular_items'              => __( 'Popular Writers' ),
		'all_items'                  => __( 'All Writers' ),
		'parent_item'                => null,
		'parent_item_colon'          => null,
		'edit_item'                  => __( 'Edit Writer' ),
		'update_item'                => __( 'Update Writer' ),
		'add_new_item'               => __( 'Add New Writer' ),
		'new_item_name'              => __( 'New Writer Name' ),
		'separate_items_with_commas' => __( 'Separate writers with commas' ),
		'add_or_remove_items'        => __( 'Add or remove writers' ),
		'choose_from_most_used'      => __( 'Choose from the most used writers' ),
		'not_found'                  => __( 'No writers found.' ),
		'menu_name'                  => __( 'Writers' ),
	);

	$args = array(
		'hierarchical'          => false,
		'labels'                => $labels,
		'show_ui'               => true,
		'show_admin_column'     => true,
		'update_count_callback' => '_update_post_term_count',
		'query_var'             => true,
		'rewrite'               => array( 'slug' => 'writer' ),
	);

	register_taxonomy( 'writer', 'book', $args );
}
?>

基本的な例

<?php
add_action( 'init', 'create_book_tax' );

function create_book_tax() {
	register_taxonomy(
		'genre',
		'book',
		array(
			'label' => __( 'Genre' ),
			'rewrite' => array( 'slug' => 'genre' ),
			'hierarchical' => true,
		)
	);
}
?>

参考：カスタム分類をタグのように使いたい場合は、オプションの 'update_count_callback' => '_update_post_term_count' を必ず追加します。そうしないと、一度に入力したコンマ区切りの複数の項目が、別々の値ではなく一つの値として保存されてしまいます。これは get_the_term_list や他のターム表示用関数を使うとき、非常に面倒なことになります。

プライベート分類の例

分類を一般に公開したくない場合は、それを抑制するために'public'と'rewrite'パラメータを使用することができます。それはプラグインやテーマによって内部的に使用できるようになりますが、それ自身ののURLを生成しません。

<?php
add_action( 'init', 'create_private_book_tax' );

function create_private_book_tax() {
    register_taxonomy(
        'genre',
        'book',
        array(
            'label' => __( 'Genre' ),
            'public' => false,
            'rewrite' => false,
            'hierarchical' => true,
        )
    );
}
?>

予約語

以下の予約語を避けることが非常に重要です。特にタームを $_GET や $_POST 配列を使って引き渡す場合は注意してください。もし重複すると、WordPress は何のヒントも説明も無しに 404 エラーを返します。

attachment
attachment_id
author
author_name
calendar
cat
category
category__and
category__in
category__not_in
category_name
comments_per_page
comments_popup
customize_messenger_channel
customized
cpage
day
debug
error
exact
feed
fields
hour
link_category
m
minute
monthnum
more
name
nav_menu
nonce
nopaging
offset
order
orderby
p
page
page_id
paged
pagename
pb
perm
post
post__in
post__not_in
post_format
post_mime_type
post_status
post_tag
post_type
posts
posts_per_archive_page
posts_per_page
preview
robots
s
search
second
sentence
showposts
static
subpost
subpost_id
tag
tag__and
tag__in
tag__not_in
tag_id
tag_slug__and
tag_slug__in
taxonomy
tb
term
theme
type
w
withcomments
withoutcomments
year

変更履歴

バージョン 3.6.0:
- 'not_found' ラベルを追加。
バージョン 3.5.0:
- 'show_ui' を false にすると「添付」のタクソノミーについて UI を隠す。
- 'show_admin_column' を追加。関連付けた投稿タイプにタクソノミーのカラムを自動生成できるようにした。
バージョン 2.3.0 から利用可能。

ソースファイル

register_taxonomy() は wp-includes/taxonomy.php にあります。

参考サイト

WordPress Taxonomy Generator

register_post_type()

カスタム分類: get_taxonomy(), taxonomy_exists(), register_taxonomy(), get_taxonomies(), the_taxonomies(), get_taxonomy_labels(), get_taxonomy_template(), is_object_in_taxonomy(), get_the_taxonomies(), get_post_taxonomies(), get_object_taxonomies(), is_taxonomy_hierarchical()

関数リファレンス、テンプレートタグ目次もご覧ください。

関数リファレンス/register taxonomy

目次

説明

使い方

パラメータ

引数

例

基本的な例

プライベート分類の例

予約語

変更履歴

ソースファイル

参考サイト

案内メニュー

個人用ツール

名前空間

変種

表示

その他

検索

このサイトについて

特集

リファレンス

サーバー別情報

ドキュメント整備

協力・貢献

WordPress関連リンク

ツール

他言語版

関数リファレンス/register taxonomy

目次

説明

使い方

パラメータ

引数

例

基本的な例

プライベート分類の例

予約語

変更履歴

ソースファイル

参考サイト

関連情報

案内メニュー

検索