get_attachment_link()

💡 云策文档标注

概述

get_attachment_link() 函数用于获取附件的固定链接（permalink），可在 WordPress Loop 内外使用。它根据站点是否启用“漂亮”固定链接结构返回不同格式的链接，并可通过 attachment_link 过滤器修改输出。

关键要点

函数返回附件的固定链接，而非直接文件链接（使用 wp_get_attachment_url() 获取文件链接）。
接受两个可选参数：$post（附件 ID 或对象，默认 null）和 $leavename（是否保留页面名称，默认 false）。
启用漂亮固定链接时，返回如 http://wp.example.net/path_to_post/post_name/attachment_name 的链接；否则返回如 http://wp.example.net/?attachment_id=n 的链接。
输出可通过 attachment_link 过滤器进行自定义。
注意：get_attachment_link() 返回 URI 字符串，而 wp_get_attachment_link() 返回 HTML 超链接。

代码示例

// 基本用法示例
$attachment_link = get_attachment_link( $post_id );
echo $attachment_link;

注意事项

函数内部处理逻辑包括检查父文章有效性、使用 WP_Rewrite 判断固定链接结构，并应用过滤器。
相关函数如 wp_force_plain_post_permalink()、is_post_type_viewable() 等用于辅助确定链接格式。

📄 原文内容

Retrieves the permalink for an attachment.

Description

This can be used in the WordPress Loop or outside of it.

Parameters

$postint|WP_Postoptional: Post ID or object. Default uses the global $post.

Default:null
$leavenamebooloptional: Whether to keep the page name.

Default:false

More Information

Under a “pretty” permalink structure, the function returns something like http://wp.example.net/path_to_post/post_name/attachment_name.

Under the default permalink structure — or if WordPress can’t construct a pretty URI — the function returns something like http://wp.example.net/?attachment_id=n, where n is the attachment ID number.

You can change the output of this function through the attachment_link filter.

If you want a direct link to the attached file (instead of the attachment page), you can use the function wp_get_attachment_url(id) instead.

Note: that get_attachment_link actually returns an URI, whereas wp_get_attachment_link() returns an HTML hyperlink.

Source

function get_attachment_link( $post = null, $leavename = false ) {
	global $wp_rewrite;

	$link = false;

	$post             = get_post( $post );
	$force_plain_link = wp_force_plain_post_permalink( $post );
	$parent_id        = $post->post_parent;
	$parent           = $parent_id ? get_post( $parent_id ) : false;
	$parent_valid     = true; // Default for no parent.
	if (
		$parent_id &&
		(
			$post->post_parent === $post->ID ||
			! $parent ||
			! is_post_type_viewable( get_post_type( $parent ) )
		)
	) {
		// Post is either its own parent or parent post unavailable.
		$parent_valid = false;
	}

	if ( $force_plain_link || ! $parent_valid ) {
		$link = false;
	} elseif ( $wp_rewrite->using_permalinks() && $parent ) {
		if ( 'page' === $parent->post_type ) {
			$parentlink = _get_page_link( $post->post_parent ); // Ignores page_on_front.
		} else {
			$parentlink = get_permalink( $post->post_parent );
		}

		if ( is_numeric( $post->post_name ) || str_contains( get_option( 'permalink_structure' ), '%category%' ) ) {
			$name = 'attachment/' . $post->post_name; // <permalink>/<int>/ is paged so we use the explicit attachment marker.
		} else {
			$name = $post->post_name;
		}

		if ( ! str_contains( $parentlink, '?' ) ) {
			$link = user_trailingslashit( trailingslashit( $parentlink ) . '%postname%' );
		}

		if ( ! $leavename ) {
			$link = str_replace( '%postname%', $name, $link );
		}
	} elseif ( $wp_rewrite->using_permalinks() && ! $leavename ) {
		$link = home_url( user_trailingslashit( $post->post_name ) );
	}

	if ( ! $link ) {
		$link = home_url( '/?attachment_id=' . $post->ID );
	}

	/**
	 * Filters the permalink for an attachment.
	 *
	 * @since 2.0.0
	 * @since 5.6.0 Providing an empty string will now disable
	 *              the view attachment page link on the media modal.
	 *
	 * @param string $link    The attachment's permalink.
	 * @param int    $post_id Attachment ID.
	 */
	return apply_filters( 'attachment_link', $link, $post->ID );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘attachment_link’, string $link, int $post_id ): Filters the permalink for an attachment.

Uses	Description
wp_force_plain_post_permalink()`wp-includes/link-template.php`	Determine whether post should always use a plain permalink structure.
is_post_type_viewable()`wp-includes/post.php`	Determines whether a post type is considered “viewable”.
_get_page_link()`wp-includes/link-template.php`	Retrieves the page permalink.
user_trailingslashit()`wp-includes/link-template.php`	Retrieves a trailing-slashed string if the site is set for adding trailing slashes.
get_post_type()`wp-includes/post.php`	Retrieves the post type of the current post or of a given post.
WP_Rewrite::using_permalinks()`wp-includes/class-wp-rewrite.php`	Determines whether permalinks are being used.
trailingslashit()`wp-includes/formatting.php`	Appends a trailing slash.
home_url()`wp-includes/link-template.php`	Retrieves the URL for the current site where the front end is accessible.
get_permalink()`wp-includes/link-template.php`	Retrieves the full permalink for the current post or post ID.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_option()`wp-includes/option.php`	Retrieves an option value based on an option name.
get_post()`wp-includes/post.php`	Retrieves post data given a post ID or post object.

Show 7 more Show less

Used by	Description
WP_Widget_Media_Image::render_media()`wp-includes/widgets/class-wp-widget-media-image.php`	Render the media on the frontend.
image_media_send_to_editor()`wp-admin/includes/media.php`	Retrieves the media element HTML to send to the editor.
media_upload_form_handler()`wp-admin/includes/media.php`	Handles form submissions for the legacy media uploader.
image_link_input_fields()`wp-admin/includes/media.php`	Retrieves HTML for the Link URL buttons with the default link type as specified.
_fix_attachment_links()`wp-admin/includes/post.php`	Replaces hrefs of attachment anchors with up-to-date permalinks.
wp_ajax_send_attachment_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending an attachment to the editor via AJAX.
get_the_attachment_link()`wp-includes/deprecated.php`	Retrieve HTML content of attachment image with link.
get_permalink()`wp-includes/link-template.php`	Retrieves the full permalink for the current post or post ID.
wp_get_attachment_link()`wp-includes/post-template.php`	Retrieves an attachment page link using an image or icon, if possible.
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.
redirect_canonical()`wp-includes/canonical.php`	Redirects incoming links to the proper URL based on the site url.

Show 6 more Show less

Changelog

Version	Description
2.0.0	Introduced.

User Contributed Notes

Skip to note 3 content

Codex

11 years ago

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
Default Usage
As the tag does not display the permalink, the example uses the PHP echo command.
```
<a href="<?php echo esc_url( $attachment_page ); ?>"></a>
```
Log in to add feedback

Skip to note 4 content

Codex

11 years ago

Display attached images and titles as a list
To display the images attached to a certain page and display them as a list of bullets you can use the following:

<ul>
 'attachment',
		'numberposts' => -1,
		'post_status' => null,
		'post_parent' => $post->ID
	);

	$attachments = get_posts( $args );
	if ( $attachments ) {
		foreach ( $attachments as $attachment ) {
			echo '<li>';
			the_attachment_link( $attachment->ID, true );
			echo '<p>';
			echo apply_filters( 'the_title', $attachment->post_title );
			echo '</p></li>';
		}
	}
endwhile; endif; ?>
</ul>

云策 WordPress 开发者社区

函数文档