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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(en:Function Reference/add post meta 13:18, 9 November 2009 GeertDD)
 
(説明: 誤記訂正。)
 
(3人の利用者による、間の5版が非表示)
1行目: 1行目:
==Description==
+
{{CheckTrans}}
  
'''add_post_meta''' adds a custom (meta) field to the specified post (or page).
+
<div id="Description">
 +
== 説明 ==
 +
</div>
  
If the <tt>$unique</tt> parameter is set to <var>true</var> and the specified meta key already exists, the function returns <var>false</var> and makes no changes; otherwise, it returns <var>true</var>.
+
'''add_post_meta()''' は、指定した投稿や固定ページへ[[カスタムフィールドの使い方|カスタムフィールド]](「メタデータ」とも呼ばれます)を追加します。どんな[[投稿タイプ]]の投稿でも構いません。ひとつのカスタムフィールドは、実際にはキーと値の組です。
  
==Usage==
+
<tt>$unique</tt> パラメータに <var>true</var> を指定しており、そのキーが既に存在している場合、この関数は何もしないで <var>false</var> を返します。それ以外の場合は、同じキーでカスタムフィールドを追加して <var>true</var> を返します。すでに存在しているカスタムフィールドの値を更新したいときは、代わりに <tt>[[関数リファレンス/update_post_meta|update_post_meta()]]</tt> を使ってください。
  
%%% <?php add_post_meta($post_id, $meta_key, $meta_value, $unique); ?> %%%
+
<div id="Usage">
 +
== 使い方 ==
 +
</div>
  
==Parameters==
+
<?php add_post_meta( $post_id, $meta_key, $meta_value, $unique ); ?>
  
{{Parameter|$post_id|integer|The ID of the post to which you will add a custom field.}}
+
<div id="Parameters">
{{Parameter|$meta_key|string|The key of the custom field you will add.}}
+
== パラメータ ==
{{Parameter|$meta_value|string|The value of the custom field you will add.}}
+
</div>
{{Parameter|$unique|boolean|Whether or not you want the key to be unique. When set to true, this will ensure that there is not already a custom field attached to the post with <tt>$meta_key</tt> as it's key, and, if such a field already exists, the key will not be added.|optional|false}}
+
  
==Examples==
+
{{Parameter|$post_id|整数|カスタムフィールドを追加する投稿の ID。}}
 +
{{Parameter|$meta_key|文字列|カスタムフィールドのキー。}}
 +
{{Parameter|$meta_value|mixed|カスタムフィールドの値。配列を与えるとシリアライズされて文字列が格納されます。}}
 +
{{Parameter|$unique|真偽値|キーをユニークにするかどうか。<var>true</var> のときは、指定した投稿に <tt>$meta_key</tt> を持つカスタムフィールドが無いときのみ追加し、すでにカスタムフィールドが存在していれば追加されません。|オプション|false}}
  
===Default Usage===
+
<div id="Return">
 +
== 戻り値 ==
 +
</div>
  
<?php add_post_meta(68, 'my_key', 47); ?>
+
{{Return||真偽値&#124;整数|成功すると、追加された行(カスタムフィールド)の ID を返します。これは <tt>true</tt> として判定できます。<tt>$unique</tt> 引数が <tt>true</tt> で、指定されたキーを持つカスタムフィールドが既にあると、<tt>false</tt> を返します。}}
  
===Adding or updating a unique field===
+
<div id="Examples">
 +
== 用例 ==
 +
</div>
  
Adds a new field if the key doesn't exist, or updates the existing field.
+
<div id="Default_Usage">
(UPDATE: If the fourth parameter of add_post_meta is set to true, the field will not be updated if it already exists (tested on WP 2.6.2). Use <tt>if (!update_post_meta(...)) add_post_meta(...))</tt>.
+
=== デフォルトの使い方 ===
 +
</div>
  
  <?php add_post_meta(7, 'fruit', 'banana', true) or update_post_meta(7, 'fruit', 'banana'); ?>
+
ID が 68 の投稿に、キーが <tt>my_key</tt> で値が 47 のカスタムフィールドを追加します。
  
===Other Examples===
+
<?php add_post_meta( 68, 'my_key', 47 ); ?>
  
If you wanted to make sure that there were no fields with the key ''"my_key"'', before adding it:
+
参考: 既に <tt>my_key</tt> というキーを持つカスタムフィールドが存在していても追加します。
  <?php add_post_meta(68, 'my_key', '47', true); ?>
+
 
To add several values to the key ''"my_key"'':
+
=== ユニークなカスタムフィールドの追加または更新 ===
<pre><?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.'); ?>
+
<pre>
 +
<?php
 +
if ( ! add_post_meta( 7, 'fruit', 'banana', true ) ) {
 +
  update_post_meta ( 7, 'fruit', 'banana' );
 +
}
 +
</pre>
 +
 
 +
=== その他の例 ===
 +
 
 +
''my_key'' というキーを持つカスタムフィールドが存在しないときだけ追加する:
 +
  <?php add_post_meta( 68, 'my_key', '47', true ); ?>
 +
 
 +
''my_key'' というキーを持つカスタムフィールドを複数追加する:
 +
<pre>
 +
<?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.' ); ?>
 
...</pre>
 
...</pre>
For a more detailed example, go to the [[Function Reference/post meta Function Examples|post_meta Functions Examples]] page.
 
  
=== Making a "Hidden" Custom Field ===
+
さらに詳しい例は [[関数リファレンス/post meta 関数の例|post_meta 関数の例]] を見てください。
  
If you are a plugin/theme developer and you are planning to use custom fields to store parameters related to your plugin or template, it is interesting to note that WordPress won't show keys starting with an "_" (underscore) in the custom fields list at the page/post editing page. That being said, it is a good practice to use an underscore as the first character in your custom parameters, that way your settings are stored as custom fields, but they won't display in the custom fields list in the admin UI.
+
<div id="Hidden_Custom_Fields">
 +
=== ''見えない'' カスタムフィールドを作る ===
 +
</div>
  
The following example:
+
プラグインやテーマの開発者なら、カスタムフィールドをプラグインやテーマ用のパラメータを保存するために使いたいことがあるかもしれません。"<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'' のユニークなカスタムフィールドを追加しますが、投稿や固定ページの編集画面には表示されません。
 
  <?php add_post_meta(68, '_color', 'red', true); ?>
 
  <?php add_post_meta(68, '_color', 'red', true); ?>
will add a unique custom field with the key name "_color" and the value "red" but this custom field will not display in the page/post editing page.
 
  
==Related==
+
<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>
  
 
{{Post Meta Tags}}
 
{{Post Meta Tags}}
  
 
{{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最新版との差分