当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「関数リファレンス/add post meta」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(残りを和訳。「戻り値」セクションを追加。)
(説明: 誤記訂正。)
 
5行目: 5行目:
 
</div>
 
</div>
  
'''add_post_meta()''' は、指定した投稿や固定ページ[[カスタムフィールドの使い方|カスタムフィールド]](「メタデータ」とも呼ばれます)を追加します。どんな[[投稿タイプ]]の投稿でも構いません。<!-- A custom field is effectively a key–value pair. -->
+
'''add_post_meta()''' は、指定した投稿や固定ページへ[[カスタムフィールドの使い方|カスタムフィールド]](「メタデータ」とも呼ばれます)を追加します。どんな[[投稿タイプ]]の投稿でも構いません。ひとつのカスタムフィールドは、実際にはキーと値の組です。
  
 
<tt>$unique</tt> パラメータに <var>true</var> を指定しており、そのキーが既に存在している場合、この関数は何もしないで <var>false</var> を返します。それ以外の場合は、同じキーでカスタムフィールドを追加して <var>true</var> を返します。すでに存在しているカスタムフィールドの値を更新したいときは、代わりに <tt>[[関数リファレンス/update_post_meta|update_post_meta()]]</tt> を使ってください。
 
<tt>$unique</tt> パラメータに <var>true</var> を指定しており、そのキーが既に存在している場合、この関数は何もしないで <var>false</var> を返します。それ以外の場合は、同じキーでカスタムフィールドを追加して <var>true</var> を返します。すでに存在しているカスタムフィールドの値を更新したいときは、代わりに <tt>[[関数リファレンス/update_post_meta|update_post_meta()]]</tt> を使ってください。

2015年8月28日 (金) 00:53時点における最新版

この項目「関数リファレンス/add post meta」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

add_post_meta() は、指定した投稿や固定ページへカスタムフィールド(「メタデータ」とも呼ばれます)を追加します。どんな投稿タイプの投稿でも構いません。ひとつのカスタムフィールドは、実際にはキーと値の組です。

$unique パラメータに true を指定しており、そのキーが既に存在している場合、この関数は何もしないで false を返します。それ以外の場合は、同じキーでカスタムフィールドを追加して true を返します。すでに存在しているカスタムフィールドの値を更新したいときは、代わりに update_post_meta() を使ってください。

使い方

<?php add_post_meta( $post_id, $meta_key, $meta_value, $unique ); ?>

パラメータ

$post_id
整数) (必須) カスタムフィールドを追加する投稿の ID。
初期値: なし
$meta_key
文字列) (必須) カスタムフィールドのキー。
初期値: なし
$meta_value
mixed) (必須) カスタムフィールドの値。配列を与えるとシリアライズされて文字列が格納されます。
初期値: なし
$unique
真偽値) (オプション) キーをユニークにするかどうか。true のときは、指定した投稿に $meta_key を持つカスタムフィールドが無いときのみ追加し、すでにカスタムフィールドが存在していれば追加されません。
初期値: false

戻り値

(真偽値|整数) 
成功すると、追加された行(カスタムフィールド)の ID を返します。これは true として判定できます。$unique 引数が true で、指定されたキーを持つカスタムフィールドが既にあると、false を返します。

用例

デフォルトの使い方

ID が 68 の投稿に、キーが my_key で値が 47 のカスタムフィールドを追加します。

<?php add_post_meta( 68, 'my_key', 47 ); ?>

参考: 既に my_key というキーを持つカスタムフィールドが存在していても追加します。

ユニークなカスタムフィールドの追加または更新

キーが存在しない場合は新しくカスタムフィールドを追加し、キーが存在する場合はカスタムフィールドを更新します。

<?php
if ( ! add_post_meta( 7, 'fruit', 'banana', true ) ) { 
   update_post_meta ( 7, 'fruit', 'banana' );
}

その他の例

my_key というキーを持つカスタムフィールドが存在しないときだけ追加する:

<?php add_post_meta( 68, 'my_key', '47', true ); ?>

my_key というキーを持つカスタムフィールドを複数追加する:

<?php add_post_meta( 68, 'my_key', '47' ); ?>
<?php add_post_meta( 68, 'my_key', '682' ); ?>
<?php add_post_meta( 68, 'my_key', 'The quick, brown fox jumped over the lazy dog.' ); ?>
...

さらに詳しい例は post_meta 関数の例 を見てください。

見えない カスタムフィールドを作る

プラグインやテーマの開発者なら、カスタムフィールドをプラグインやテーマ用のパラメータを保存するために使いたいことがあるかもしれません。"_"(アンダースコア)で始まるキーを持つカスタムフィールドは、投稿や固定ページの編集画面に表示されず、the_meta() では取得されないので、そのような内部的な 見えない パラメータを扱うのに適しています。

以下の例は、キーが _color で値が red のユニークなカスタムフィールドを追加しますが、投稿や固定ページの編集画面には表示されません。

<?php add_post_meta(68, '_color', 'red', true); ?>

隠された配列

さらに、$meta_value 引数が配列だった場合、キー名がアンダースコアで始まらなくても投稿や固定ページの編集画面に表示されません。

参考

文字のエスケープ

カスタムフィールドの値は stripslashes() 関数を通して渡されるので、「\」(バックスラッシュ)でエスケープされたコンテンツについて注意する必要があります。この動作内容と、対応方法の例については、update_post_meta() の説明をご覧ください。

ソースコード

add_post_meta()wp-includes/post.php にあります。

更新履歴

新規導入: 1.5.0


カスタムフィールド: the_meta(), get_post_meta(), add_post_meta(), update_post_meta(), delete_post_meta(), get_post_custom(), get_post_custom_values(), get_post_custom_keys() (post_meta 関数の例 /en も参照)


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


最新英語版: WordPress Codex » Function Reference/add post meta最新版との差分