云策 WordPress 开发者社区

函数文档

the_meta()

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

概述

the_meta() 是一个 WordPress 内置函数，用于显示当前文章的自定义字段列表，格式化为无序列表。该函数已弃用，建议使用 get_post_meta() 替代。

关键要点

  • the_meta() 用于在循环内或单篇文章模板中显示自定义字段，忽略以下划线开头的 meta_key。
  • 函数已弃用（自版本 6.0.2 起），推荐使用 get_post_meta() 进行自定义字段操作。
  • 输出格式为键值对列表，支持国际化翻译，可通过 the_meta_key 过滤器自定义 HTML 输出。

代码示例

function the_meta() {
    _deprecated_function( __FUNCTION__, '6.0.2', 'get_post_meta()' );
    $keys = get_post_custom_keys();
    if ( $keys ) {
        $li_html = '';
        foreach ( (array) $keys as $key ) {
            $keyt = trim( $key );
            if ( is_protected_meta( $keyt, 'post' ) ) {
                continue;
            }
            $values = array_map( 'trim', get_post_custom_values( $key ) );
            $value  = implode( ', ', $values );
            $html = sprintf(
                "%s %sn",
                esc_html( sprintf( _x( '%s:', 'Post custom field name' ), $key ) ),
                esc_html( $value )
            );
            $li_html .= apply_filters( 'the_meta_key', $html, $key, $value );
        }
        if ( $li_html ) {
            echo "n{$li_html}n";
        }
    }
}

注意事项

  • 使用 the_meta() 前需确保在 The Loop 或单篇文章上下文中，否则可能无法正确获取数据。
  • 由于函数已弃用，新开发应避免使用，转而采用 get_post_meta() 等现代方法处理自定义字段。
  • 输出支持本地化，不同语言环境可能调整冒号前的空格字符，如法语使用非断空格。
📄 原文内容

Displays a list of post custom fields.

More Information

This is a simple built-in function for displaying custom fields for the current post, known as the “post-meta” (stored in the wp_postmeta table). It formats the data into an unordered list (see output below).

It must be used from within The Loop or in a theme file that handles data from a single post (e.g. single.php). the_meta() will ignore meta_keys (i.e. field names) that begin with an underscore.

For more information on this tag, see Custom Fields.

Source

function the_meta() {
	_deprecated_function( __FUNCTION__, '6.0.2', 'get_post_meta()' );
	$keys = get_post_custom_keys();
	if ( $keys ) {
		$li_html = '';
		foreach ( (array) $keys as $key ) {
			$keyt = trim( $key );
			if ( is_protected_meta( $keyt, 'post' ) ) {
				continue;
			}

			$values = array_map( 'trim', get_post_custom_values( $key ) );
			$value  = implode( ', ', $values );

			$html = sprintf(
				"<li><span class='post-meta-key'>%s</span> %s</li>n",
				/* translators: %s: Post custom field name. */
				esc_html( sprintf( _x( '%s:', 'Post custom field name' ), $key ) ),
				esc_html( $value )
			);

			/**
			 * Filters the HTML output of the li element in the post custom fields list.
			 *
			 * @since 2.2.0
			 *
			 * @param string $html  The HTML output for the li element.
			 * @param string $key   Meta key.
			 * @param string $value Meta value.
			 */
			$li_html .= apply_filters( 'the_meta_key', $html, $key, $value );
		}

		if ( $li_html ) {
			echo "<ul class='post-meta'>n{$li_html}</ul>n";
		}
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘the_meta_key’, string $html, string $key, string $value )

Filters the HTML output of the li element in the post custom fields list.

Uses Description
get_post_custom_keys()wp-includes/post.php

Retrieves meta field names for a post.
get_post_custom_values()wp-includes/post.php

Retrieves values for a custom post field.
is_protected_meta()wp-includes/meta.php

Determines whether a meta key is considered protected.
_x()wp-includes/l10n.php

Retrieves translated string with gettext context.
esc_html()wp-includes/formatting.php

Escaping for HTML blocks.
_deprecated_function()wp-includes/functions.php

Marks a function as deprecated and inform when it has been used.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 4 moreShow less

Changelog

Version Description
1.2.0 Introduced.

User Contributed Notes

  2. Skip to note 4 content


    Jb Audras


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Since revision 41583, the_meta() allow translators to manage spaces before the colon character.

    Default output:

    <ul class="post-meta">
    <li><span class='post-meta-key'>Your first meta key:</span> one or several values separated by commas</li>
    …
    <li><span class='post-meta-key'>Your second meta key:</span> one or several values separated by commas</li>
    <li><span class='post-meta-key'>Your third meta key:</span> one or several values separated by commas</li>
</ul>

    French output:

    <ul class="post-meta">
	<li><span class='post-meta-key'>Your first meta key :</span> one or several values separated by commas</li>
	…
	<li><span class='post-meta-key'>Your second meta key :</span> one or several values separated by commas</li>
	<li><span class='post-meta-key'>Your third meta key :</span> one or several values separated by commas</li>
</ul>

    There is a non breaking space character before the colon character. Each Locale can handle it differently.