云策 WordPress 开发者社区

函数文档

wp_get_attachment_id3_keys()

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

概述

wp_get_attachment_id3_keys() 函数用于返回从附件存储的元数据中查找数据时使用的键值对。它根据上下文参数动态生成字段列表，并可通过过滤器进行自定义。

关键要点

  • 函数返回一个数组，包含字段键到标签的映射，用于附件元数据查询。
  • 接受两个参数：$attachment（WP_Post 对象，必需）和 $context（字符串，可选，默认为 'display'）。
  • 上下文参数影响返回的字段：'display' 上下文包括 artist、album、genre、year 和 length_formatted；'js' 上下文包括 artist、album、bitrate 和 bitrate_mode。
  • 提供过滤器 wp_get_attachment_id3_keys，允许开发者修改返回的字段列表。
  • 函数自 WordPress 3.9.0 版本引入，常用于编辑附件、AJAX 操作和媒体显示等场景。

代码示例

function wp_get_attachment_id3_keys( $attachment, $context = 'display' ) {
    $fields = array(
        'artist' => __( 'Artist' ),
        'album'  => __( 'Album' ),
    );

    if ( 'display' === $context ) {
        $fields['genre']            = __( 'Genre' );
        $fields['year']             = __( 'Year' );
        $fields['length_formatted'] = _x( 'Length', 'video or audio' );
    } elseif ( 'js' === $context ) {
        $fields['bitrate']      = __( 'Bitrate' );
        $fields['bitrate_mode'] = __( 'Bitrate Mode' );
    }

    return apply_filters( 'wp_get_attachment_id3_keys', $fields, $attachment, $context );
}

注意事项

  • 函数依赖于 WordPress 的翻译函数 __() 和 _x() 来提供本地化标签。
  • 过滤器 wp_get_attachment_id3_keys 允许在运行时调整字段，增强灵活性。
  • 在 'js' 上下文中返回的字段适用于 JavaScript 环境，如 wp_prepare_attachment_for_js() 函数。
📄 原文内容

Returns useful keys to use to lookup data from an attachment’s stored metadata.

Parameters

$attachmentWP_Postrequired
The current attachment, provided for context.
$contextstringoptional
The context. Accepts 'edit', 'display'. Default 'display'.

Return

string[] Key/value pairs of field keys to labels.

Source

function wp_get_attachment_id3_keys( $attachment, $context = 'display' ) {
	$fields = array(
		'artist' => __( 'Artist' ),
		'album'  => __( 'Album' ),
	);

	if ( 'display' === $context ) {
		$fields['genre']            = __( 'Genre' );
		$fields['year']             = __( 'Year' );
		$fields['length_formatted'] = _x( 'Length', 'video or audio' );
	} elseif ( 'js' === $context ) {
		$fields['bitrate']      = __( 'Bitrate' );
		$fields['bitrate_mode'] = __( 'Bitrate Mode' );
	}

	/**
	 * Filters the editable list of keys to look up data from an attachment's metadata.
	 *
	 * @since 3.9.0
	 *
	 * @param array   $fields     Key/value pairs of field keys to labels.
	 * @param WP_Post $attachment Attachment object.
	 * @param string  $context    The context. Accepts 'edit', 'display'. Default 'display'.
	 */
	return apply_filters( 'wp_get_attachment_id3_keys', $fields, $attachment, $context );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_get_attachment_id3_keys’, array $fields, WP_Post $attachment, string $context )

Filters the editable list of keys to look up data from an attachment’s metadata.

Uses Description
__()wp-includes/l10n.php

Retrieves the translation of $text.
_x()wp-includes/l10n.php

Retrieves translated string with gettext context.
apply_filters()wp-includes/plugin.php

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

Show 1 moreShow less

Used by Description
edit_post()wp-admin/includes/post.php

Updates an existing post with values provided in $_POST.
wp_ajax_save_attachment()wp-admin/includes/ajax-actions.php

Handles updating attachment attributes via AJAX.
attachment_id3_data_meta_box()wp-admin/includes/meta-boxes.php

Displays fields for ID3 data.
wp_prepare_attachment_for_js()wp-includes/media.php

Prepares an attachment post object for JS, where it is expected to be JSON-encoded and fit into an Attachment model.
wp_playlist_shortcode()wp-includes/media.php

Builds the Playlist shortcode output.

Changelog

Version Description
3.9.0 Introduced.