云策 WordPress 开发者社区

函数文档

get_metadata()

查看官方原文 ↗
💡 云策文档标注

概述

get_metadata() 函数用于检索指定对象类型和 ID 的元数据字段值。它根据参数返回单个值或数组，并处理元数据不存在的情况。

关键要点

  • 函数签名：get_metadata( $meta_type, $object_id, $meta_key = '', $single = false )
  • 参数：$meta_type（必需，如 'post'、'user'）、$object_id（必需）、$meta_key（可选，默认为空字符串）、$single（可选，默认为 false）
  • 返回值：根据 $single 参数返回单个值或数组；无效输入返回 false；非序列化值以字符串形式返回（如 false 为 ''，true 为 '1'）
  • 依赖函数：内部调用 get_metadata_raw() 和 get_metadata_default() 处理元数据检索和默认值

代码示例

// 示例：检索文章元数据数组
array (
  '_pingme' => array (
    0 => '1',
  ),
  '_encloseme' => array (
    0 => '1',
  ),
  'custom key 1' => array (
    0 => 'custom value 1',
    1 => 'custom value 2',
  ),
  'custom key 2' => array (
    0 => 'custom value 3',
  ),
)

注意事项

  • 当元数据不存在且 $single 为 true 时返回空字符串，为 false 时返回空数组
  • 无效 $object_id（非数字、零或负值）或未指定 $meta_type 时返回 false
  • 相关函数包括 get_post_meta()、get_user_meta() 等特定对象类型的包装函数
📄 原文内容

Retrieves the value of a metadata field for the specified object type and ID.

Description

If the meta field exists, a single value is returned if $single is true, or an array of values if it’s false.

If the meta field does not exist, the result depends on get_metadata_default() .
By default, an empty string is returned if $single is true, or an empty array if it’s false.

See also

Parameters

$meta_typestringrequired
Type of object metadata is for. Accepts 'blog', 'post', 'comment', 'term', 'user', or any other object type with an associated meta table.
$object_idintrequired
ID of the object metadata is for.
$meta_keystringoptional
Metadata key. If not specified, retrieve all metadata for the specified object. Default empty string.
$singlebooloptional
If true, return only the first value of the specified $meta_key.
This parameter has no effect if $meta_key is not specified.

Default:false

Return

mixed An array of values if $single is false.
The value of the meta field if $single is true.
False for an invalid $object_id (non-numeric, zero, or negative value), or if $meta_type is not specified.
An empty array if a valid but non-existing object ID is passed and $single is false.
An empty string if a valid but non-existing object ID is passed and $single is true.
Note: Non-serialized values are returned as strings:

  • false values are returned as empty strings ('')
  • true values are returned as '1'
  • numbers (both integer and float) are returned as strings Arrays and objects retain their original type.

Source

function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
	$value = get_metadata_raw( $meta_type, $object_id, $meta_key, $single );
	if ( ! is_null( $value ) ) {
		return $value;
	}

	return get_metadata_default( $meta_type, $object_id, $meta_key, $single );
}

View all references View on Trac View on GitHub

Uses Description
get_metadata_default()wp-includes/meta.php

Retrieves default metadata value for the specified meta key and object.
get_metadata_raw()wp-includes/meta.php

Retrieves raw metadata value for the specified object.
Used by Description
get_site_meta()wp-includes/ms-site.php

Retrieves metadata for a site.
WP_REST_Meta_Fields::update_value()wp-includes/rest-api/fields/class-wp-rest-meta-fields.php

Updates meta values.
WP_REST_Meta_Fields::get_value()wp-includes/rest-api/fields/class-wp-rest-meta-fields.php

Retrieves the meta field value.
get_registered_metadata()wp-includes/meta.php

Retrieves registered metadata for a specified object.
get_term_meta()wp-includes/taxonomy.php

Retrieves metadata for a term.
get_user_meta()wp-includes/user.php

Retrieves user meta field for a user.
get_post_meta()wp-includes/post.php

Retrieves a post meta field for the given post ID.
get_comment_meta()wp-includes/comment.php

Retrieves comment meta field for a comment.

Show 3 moreShow less

Changelog

Version Description
2.9.0 Introduced.

User Contributed Notes