云策 WordPress 开发者社区

函数文档

get_metadata_default()

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

概述

get_metadata_default() 函数用于检索指定元键和对象的默认元数据值。默认情况下，根据 $single 参数返回空字符串或空数组，并可通过过滤器进行自定义。

关键要点

  • 函数返回默认元数据值：若 $single 为 true 则返回空字符串，为 false 则返回空数组。
  • 参数包括 $meta_type（对象类型，如 'post'、'user'）、$object_id（对象ID）、$meta_key（元键）和 $single（是否返回单个值）。
  • 提供过滤器 default_{$meta_type}_metadata 以允许开发者自定义默认值。
  • 函数内部使用 wp_is_numeric_array() 确保返回数组格式正确。

代码示例

function get_metadata_default( $meta_type, $object_id, $meta_key, $single = false ) {
	if ( $single ) {
		$value = '';
	} else {
		$value = array();
	}

	$value = apply_filters( "default_{$meta_type}_metadata", $value, $object_id, $meta_key, $single, $meta_type );

	if ( ! $single && ! wp_is_numeric_array( $value ) ) {
		$value = array( $value );
	}

	return $value;
}

注意事项

  • 该函数自 WordPress 5.5.0 版本引入，主要用于 get_metadata() 等函数中处理元数据缺失的情况。
  • 过滤器名称动态生成，基于 $meta_type，例如 default_post_metadata 用于文章元数据。
📄 原文内容

Retrieves default metadata value for the specified meta key and object.

Description

By default, an empty string is returned if $single is true, or an empty array if it’s false.

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_keystringrequired
Metadata key.
$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 default values if $single is false.
The default value of the meta field if $single is true.

Source

function get_metadata_default( $meta_type, $object_id, $meta_key, $single = false ) {
	if ( $single ) {
		$value = '';
	} else {
		$value = array();
	}

	/**
	 * Filters the default metadata value for a specified meta key and object.
	 *
	 * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
	 * (blog, post, comment, term, user, or any other type with an associated meta table).
	 *
	 * Possible filter names include:
	 *
	 *  - `default_blog_metadata`
	 *  - `default_post_metadata`
	 *  - `default_comment_metadata`
	 *  - `default_term_metadata`
	 *  - `default_user_metadata`
	 *
	 * @since 5.5.0
	 *
	 * @param mixed  $value     The value to return, either a single metadata value or an array
	 *                          of values depending on the value of `$single`.
	 * @param int    $object_id ID of the object metadata is for.
	 * @param string $meta_key  Metadata key.
	 * @param bool   $single    Whether to return only the first value of the specified `$meta_key`.
	 * @param string $meta_type Type of object metadata is for. Accepts 'blog', 'post', 'comment', 'term',
	 *                          'user', or any other object type with an associated meta table.
	 */
	$value = apply_filters( "default_{$meta_type}_metadata", $value, $object_id, $meta_key, $single, $meta_type );

	if ( ! $single && ! wp_is_numeric_array( $value ) ) {
		$value = array( $value );
	}

	return $value;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( “default_{$meta_type}_metadata”, mixed $value, int $object_id, string $meta_key, bool $single, string $meta_type )

Filters the default metadata value for a specified meta key and object.

Uses Description
wp_is_numeric_array()wp-includes/functions.php

Determines if the variable is a numeric-indexed array.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
Used by Description
get_metadata()wp-includes/meta.php

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

Changelog

Version Description
5.5.0 Introduced.