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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(全体を和訳)
(説明: 誤記訂正。)
 
(2人の利用者による、間の4版が非表示)
1行目: 1行目:
 +
{{CheckTrans}}
 +
 
<div id="Description">
 
<div id="Description">
 
== 説明 ==
 
== 説明 ==
 
</div>
 
</div>
  
'''add_post_meta''' は、指定した記事や固定ページにカスタム(メタ)フィールドを追加します。
+
'''add_post_meta()''' は、指定した投稿や固定ページへ[[カスタムフィールドの使い方|カスタムフィールド]](「メタデータ」とも呼ばれます)を追加します。どんな[[投稿タイプ]]の投稿でも構いません。ひとつのカスタムフィールドは、実際にはキーと値の組です。
  
<tt>$unique</tt> パラメータに <var>true</var> を指定しており、そのメタキーが既に存在している場合、この関数は <var>false</var> を返し何もしません。それ以外の場合は、カスタムフィールドを追加し <var>true</var> を返します。
+
<tt>$unique</tt> パラメータに <var>true</var> を指定しており、そのキーが既に存在している場合、この関数は何もしないで <var>false</var> を返します。それ以外の場合は、同じキーでカスタムフィールドを追加して <var>true</var> を返します。すでに存在しているカスタムフィールドの値を更新したいときは、代わりに <tt>[[関数リファレンス/update_post_meta|update_post_meta()]]</tt> を使ってください。
  
 
<div id="Usage">
 
<div id="Usage">
11行目: 13行目:
 
</div>
 
</div>
  
  <?php add_post_meta($post_id, $meta_key, $meta_value, $unique); ?>
+
  <?php add_post_meta( $post_id, $meta_key, $meta_value, $unique ); ?>
  
 
<div id="Parameters">
 
<div id="Parameters">
19行目: 21行目:
 
{{Parameter|$post_id|整数|カスタムフィールドを追加する投稿の ID。}}
 
{{Parameter|$post_id|整数|カスタムフィールドを追加する投稿の ID。}}
 
{{Parameter|$meta_key|文字列|カスタムフィールドのキー。}}
 
{{Parameter|$meta_key|文字列|カスタムフィールドのキー。}}
{{Parameter|$meta_value|文字列|カスタムフィールドの値。}}
+
{{Parameter|$meta_value|mixed|カスタムフィールドの値。配列を与えるとシリアライズされて文字列が格納されます。}}
{{Parameter|$unique|真偽値|キーをユニークにするかどうか。<var>true</var> のときは、指定した投稿に <tt>$meta_key</tt> を持つカスタムフィールドが無いときのみ追加し、すでにカスタムフィールドが存在していれば追加されません。|optional|false}}
+
{{Parameter|$unique|真偽値|キーをユニークにするかどうか。<var>true</var> のときは、指定した投稿に <tt>$meta_key</tt> を持つカスタムフィールドが無いときのみ追加し、すでにカスタムフィールドが存在していれば追加されません。|オプション|false}}
 +
 
 +
<div id="Return">
 +
== 戻り値 ==
 +
</div>
 +
 
 +
{{Return||真偽値&#124;整数|成功すると、追加された行(カスタムフィールド)の ID を返します。これは <tt>true</tt> として判定できます。<tt>$unique</tt> 引数が <tt>true</tt> で、指定されたキーを持つカスタムフィールドが既にあると、<tt>false</tt> を返します。}}
  
 
<div id="Examples">
 
<div id="Examples">
27行目: 35行目:
  
 
<div id="Default_Usage">
 
<div id="Default_Usage">
===デフォルトの使い方===
+
=== デフォルトの使い方 ===
 
</div>
 
</div>
  
ID が68の投稿に、キーが <tt>my_key</tt> で値が47のカスタムフィールドを追加します。
+
ID が 68 の投稿に、キーが <tt>my_key</tt> で値が 47 のカスタムフィールドを追加します。
<?php add_post_meta(68, 'my_key', 47); ?>
+
  
既に <tt>my_key</tt> というキーを持つカスタムフィールドが存在していても追加します。
+
<?php add_post_meta( 68, 'my_key', 47 ); ?>
  
===ユニークなカスタムフィールドの追加と更新===
+
参考: 既に <tt>my_key</tt> というキーを持つカスタムフィールドが存在していても追加します。
 +
 
 +
=== ユニークなカスタムフィールドの追加または更新 ===
  
 
キーが存在しない場合は新しくカスタムフィールドを追加し、キーが存在する場合はカスタムフィールドを更新します。
 
キーが存在しない場合は新しくカスタムフィールドを追加し、キーが存在する場合はカスタムフィールドを更新します。
  <?php if ( !add_post_meta(7, 'fruit', 'banana', true) ) update_post_meta(7, 'fruit', 'banana'); ?>
+
<pre>
 +
<?php
 +
if ( ! add_post_meta( 7, 'fruit', 'banana', true ) ) {
 +
  update_post_meta ( 7, 'fruit', 'banana' );
 +
}
 +
</pre>
  
===その他の例===
+
=== その他の例 ===
  
''"my_key"'' キーを持つカスタムフィールドが存在しないときだけ追加する:
+
''my_key'' というキーを持つカスタムフィールドが存在しないときだけ追加する:
  <?php add_post_meta(68, 'my_key', '47', true); ?>
+
  <?php add_post_meta( 68, 'my_key', '47', true ); ?>
  
''"my_key"'' キーを持つカスタムフィールドを複数追加する:
+
''my_key'' というキーを持つカスタムフィールドを複数追加する:
<pre><?php add_post_meta(68, 'my_key', '47'); ?>
+
<pre>
<?php add_post_meta(68, 'my_key', '682'); ?>
+
<?php add_post_meta( 68, 'my_key', '47' ); ?>
<?php add_post_meta(68, 'my_key', 'The quick, brown fox jumped over the lazy dog.'); ?>
+
<?php add_post_meta( 68, 'my_key', '682' ); ?>
 +
<?php add_post_meta( 68, 'my_key', 'The quick, brown fox jumped over the lazy dog.' ); ?>
 
...</pre>
 
...</pre>
  
さらに詳しい例は [[関数リファレンス/post meta 関数の例|post meta 関数の例]] を見てください。
+
さらに詳しい例は [[関数リファレンス/post meta 関数の例|post_meta 関数の例]] を見てください。
  
 +
<div id="Hidden_Custom_Fields">
 
=== ''見えない'' カスタムフィールドを作る ===
 
=== ''見えない'' カスタムフィールドを作る ===
 +
</div>
  
プラグインやテーマの開発者なら、カスタムフィールドをプラグインやテーマ用のパラメータを保存するために使いたいことがあるかもしれません。"_" (アンダースコア)で始まるキーを持つカスタムフィールドは記事や固定ページの編集画面に表示されないので、そのような内部的な ''見えない'' パラメータを扱うのに適しています。
+
プラグインやテーマの開発者なら、カスタムフィールドをプラグインやテーマ用のパラメータを保存するために使いたいことがあるかもしれません。"<tt>_</tt>"(アンダースコア)で始まるキーを持つカスタムフィールドは、投稿や固定ページの編集画面に表示されず、<tt>[[テンプレートタグ/the_meta|the_meta()]]</tt> では取得されないので、そのような内部的な ''見えない'' パラメータを扱うのに適しています。<!-- This can be for example used to show these custom fields in an unusual way by using the <tt>[[Function Reference/add_meta_box | add_meta_box()]]</tt> function. -->
  
以下の例は、キーが ''_color'' で値が ''red'' のユニークなカスタムフィールドを追加しますが、記事や固定ページの編集画面には表示されません。
+
以下の例は、キーが ''_color'' で値が ''red'' のユニークなカスタムフィールドを追加しますが、投稿や固定ページの編集画面には表示されません。
 
  <?php add_post_meta(68, '_color', 'red', true); ?>
 
  <?php add_post_meta(68, '_color', 'red', true); ?>
 +
 +
<div id="Hidden_Arrays">
 +
==== 隠された配列 ====
 +
</div>
 +
 +
さらに、<tt>$meta_value</tt> 引数が配列だった場合、キー名がアンダースコアで始まらなくても投稿や固定ページの編集画面に表示されません。
 +
 +
== 参考 ==
 +
* 内部で <tt>[[関数リファレンス/add_metadata | add_metadata()]]</tt> を使用します。
 +
 +
<div id="Character_Escaping">
 +
=== 文字のエスケープ ===
 +
</div>
 +
 +
カスタムフィールドの値は <tt>[http://php.net/stripslashes stripslashes()]</tt> 関数を通して渡されるので、「<tt>\</tt>」(バックスラッシュ)でエスケープされたコンテンツについて注意する必要があります。この動作内容と、対応方法の例については、<tt>[[関数リファレンス/update_post_meta#Character_Escaping|update_post_meta()]]</tt> の説明をご覧ください。
 +
 +
== ソースコード ==
 +
 +
<tt>add_post_meta()</tt> は {{Trac|wp-includes/post.php}} にあります。
 +
 +
== 更新履歴 ==
 +
 +
新規導入: 1.5.0
  
 
<div id="Related">
 
<div id="Related">
67行目: 107行目:
  
 
{{Tag Footer}}
 
{{Tag Footer}}
{{原文|Function Reference/add post meta|80014}}<!-- 13:18, 9 November 2009 GeertDD -->
+
 
[[Category:Functions]]
+
{{原文|Function Reference/add post meta|151931}} <!-- 15:10, 4 June 2015 Jdgrimes -->
 +
 
 +
{{DEFAULTSORT:Add_post_meta}}
 +
[[Category:関数]]
 +
 
 
[[en:Function Reference/add post meta]]
 
[[en:Function Reference/add post meta]]
 +
[[ru:Справочник_по_функциям/add_post_meta]]
 +
[[es:Referencia de Funciones/add_post_meta]]
 +
[[pt-br:Funções e Referências/add_post_meta]]

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最新版との差分