wordpress开发 – WordPress 常用函数 / add_post_meta

简介

add_post_meta 添加一个一个自定义字段（Custom Field）到指定的日志，页面或者 post type 中。

如果 $unique 参数设置为 true，并且指定的 meta key 已存在，那么这个函数返回 false 并且不对现有的字段做任何修改，否则添加字段并返回 true。

用法

1
<span class="token deliminator"><?php</span> add_post_meta<span class="token punctuation">(</span><span class="token variable">$post_id</span><span class="token punctuation">,</span> <span class="token variable">$meta_key</span><span class="token punctuation">,</span> <span class="token variable">$meta_value</span><span class="token punctuation">,</span> <span class="token variable">$unique</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token deliminator">?></span>

参数

$post_id
(integer) (required) 将要添加自定义字段的日志 ID。
Default: None

$meta_key
(string) (required) 将要添加自定义字段的名称（key）。
Default: None

$meta_value
(mixed) (required) 将要添加自定义字段的值，如果是一个数组，将会被序列化成字符串。
Default: None

$unique
(boolean) (optional) 设置当前的 key 是否为唯一的，当设置为 true，将保证当前日志没有以 $meta_key 作为 key 的自定义字段，并且如果已经存在，则添加不成功。
Default: false

返回值

(bool)
添加成功返回 true，否则返回 false。

实例

基本用法

1
<span class="token deliminator"><?php</span> add_post_meta<span class="token punctuation">(</span><span class="token number">68</span><span class="token punctuation">,</span> <span class="token string">'my_key'</span><span class="token punctuation">,</span> <span class="token number">47</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token deliminator">?></span>

添加或者更新唯一的自定义字段

如果 key 还不存在，就添加一个新的自定义字段，如果存在，就更新它：

1
<span class="token deliminator"><?php</span> add_post_meta<span class="token punctuation">(</span><span class="token number">7</span><span class="token punctuation">,</span> <span class="token string">'fruit'</span><span class="token punctuation">,</span> <span class="token string">'banana'</span><span class="token punctuation">,</span> <span class="token boolean">true</span><span class="token punctuation">)</span> <span class="token keyword">or</span> update_post_meta<span class="token punctuation">(</span><span class="token number">7</span><span class="token punctuation">,</span> <span class="token string">'fruit'</span><span class="token punctuation">,</span> <span class="token string">'banana'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token deliminator">?></span>

添加多个值的自定义字段

给 key 名为 “my_key” 的自定义字段添加多个值：

1
2
3
4
<span class="token deliminator"><?php</span> add_post_meta<span class="token punctuation">(</span><span class="token number">68</span><span class="token punctuation">,</span> <span class="token string">'my_key'</span><span class="token punctuation">,</span> <span class="token string">'47'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token deliminator">?></span>
<span class="token deliminator"><?php</span> add_post_meta<span class="token punctuation">(</span><span class="token number">68</span><span class="token punctuation">,</span> <span class="token string">'my_key'</span><span class="token punctuation">,</span> <span class="token string">'682'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token deliminator">?></span>
<span class="token deliminator"><?php</span> add_post_meta<span class="token punctuation">(</span><span class="token number">68</span><span class="token punctuation">,</span> <span class="token string">'my_key'</span><span class="token punctuation">,</span> <span class="token string">'The quick, brown fox jumped over the lazy dog.'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token deliminator">?></span>
<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>

添加一个“隐藏”的自定义字段

默认情况下，你添加的自定义字段会在后台日志或者页面编辑器下面自定义区域显示，或者会被 the_meta() 函数可以调用，但是如果你是一个 WordPress 插件或者主题开发者，打算使用自定义字段来存储一些数据，并且不希望用户能够自己修改它，你可以通过给自定义字段的 key 以下划线（“_”）开始，则不会在后台显示。

1
<span class="token deliminator"><?php</span> add_post_meta<span class="token punctuation">(</span><span class="token number">68</span><span class="token punctuation">,</span> <span class="token string">'_color'</span><span class="token punctuation">,</span> <span class="token string">'red'</span><span class="token punctuation">,</span> <span class="token boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token deliminator">?></span>

比如上面实例就是添加了一个 key 名为 “_color” 值为 “red” 的自定义字段，这个字段将不会显示在在后台的日志或者页面的编辑页面。

另外，如果 $meta_value 是一个数组，也不会显示在后台的日志或者页面的编辑页面。

修改记录

Since 1.5.0

源文件

wp-includes/post.php