get_the_password_form()

💡 云策文档标注

概述

get_the_password_form() 函数用于生成受密码保护文章的密码表单 HTML 内容。它接受一个可选的帖子参数，并返回包含表单字段和错误消息的字符串，可通过过滤器进行自定义。

关键要点

函数参数：$post（可选），可以是帖子 ID 或 WP_Post 对象，默认为全局 $post。
返回值：字符串，包含密码表单的 HTML 输出。
核心功能：根据帖子状态生成密码输入表单，包括重定向字段、错误消息和国际化文本。
过滤器支持：提供 the_password_form 和 the_password_form_incorrect_password 过滤器，允许开发者自定义表单 HTML 和无效密码消息。
错误处理：当用户输入无效密码时，会显示过滤后的错误消息，并添加 ARIA 属性和 CSS 类以增强可访问性。

代码示例

add_filter( 'the_password_form', 'wporg_password_form' );
function wporg_password_form() {
    global $post;
    $label = 'pwbox-' . ( empty( $post->ID ) ? rand() : $post->ID );
    $output = '
    ' . esc_html__( 'New Text for my protected post', 'text-domain' ) . '
    ' . esc_html__( 'Password:', 'text-domain' ) . ' 
    ' . esc_html__( 'Additional text to be placed below', 'text-domain' ) . '
    ';
    return $output;
}

注意事项

密码字段在数据库中的长度限制为 255 个字符，不受 HTML 属性如 minlength 或 maxlength 的影响。
使用过滤器时，需注意函数参数的变化，例如 the_password_form 过滤器在 5.8.0 版本添加了 $post 参数，在 6.8.0 版本添加了 $invalid_password 参数。
函数内部使用了多个 WordPress 核心函数，如 get_post()、esc_attr() 和 apply_filters()，确保安全性和可扩展性。

📄 原文内容

Retrieves protected post password form content.

Parameters

$postint|WP_Postoptional: Post ID or WP_Post object. Default is global $post.

Return

string HTML content for password form for password-protected post.

Source

function get_the_password_form( $post = 0 ) {
	$post                  = get_post( $post );
	$field_id              = 'pwbox-' . ( empty( $post->ID ) ? wp_rand() : $post->ID );
	$invalid_password      = '';
	$invalid_password_html = '';
	$aria                  = '';
	$class                 = '';
	$redirect_field        = '';

	// If the referrer is the same as the current request, the user has entered an invalid password.
	if ( ! empty( $post->ID ) && wp_get_raw_referer() === get_permalink( $post->ID ) && isset( $_COOKIE[ 'wp-postpass_' . COOKIEHASH ] ) ) {
		/**
		 * Filters the invalid password message shown on password-protected posts.
		 * The filter is only applied if the post is password-protected.
		 *
		 * @since 6.8.0
		 *
		 * @param string  $text The message shown to users when entering an invalid password.
		 * @param WP_Post $post Post object.
		 */
		$invalid_password      = apply_filters( 'the_password_form_incorrect_password', __( 'Invalid password.' ), $post );
		$invalid_password_html = '<div class="post-password-form-invalid-password" role="alert"><p id="error-' . $field_id . '">' . $invalid_password . '</p></div>';
		$aria                  = ' aria-describedby="error-' . $field_id . '"';
		$class                 = ' password-form-error';
	}

	if ( ! empty( $post->ID ) ) {
		$redirect_field = sprintf(
			'<input type="hidden" name="redirect_to" value="%s" />',
			esc_attr( get_permalink( $post->ID ) )
		);
	}

	$output = '<form action="' . esc_url( site_url( 'wp-login.php?action=postpass', 'login_post' ) ) . '" class="post-password-form' . $class . '" method="post">' . $redirect_field . $invalid_password_html . '
	<p>' . __( 'This content is password-protected. To view it, please enter the password below.' ) . '</p>
	<p><label for="' . $field_id . '">' . __( 'Password:' ) . ' <input name="post_password" id="' . $field_id . '" type="password" spellcheck="false" required size="20"' . $aria . ' /></label> <input type="submit" name="Submit" value="' . esc_attr_x( 'Enter', 'post password form' ) . '" /></p></form>
	';

	/**
	 * Filters the HTML output for the protected post password form.
	 *
	 * If modifying the password field, please note that the WordPress database schema
	 * limits the password field to 255 characters regardless of the value of the
	 * `minlength` or `maxlength` attributes or other validation that may be added to
	 * the input.
	 *
	 * @since 2.7.0
	 * @since 5.8.0 Added the `$post` parameter.
	 * @since 6.8.0 Added the `$invalid_password` parameter.
	 *
	 * @param string  $output           The password form HTML output.
	 * @param WP_Post $post             Post object.
	 * @param string  $invalid_password The invalid password message.
	 */
	return apply_filters( 'the_password_form', $output, $post, $invalid_password );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘the_password_form’, string $output, WP_Post $post, string $invalid_password ): Filters the HTML output for the protected post password form.
apply_filters( ‘the_password_form_incorrect_password’, string $text, WP_Post $post ): Filters the invalid password message shown on password-protected posts.

Uses	Description
wp_get_raw_referer()`wp-includes/functions.php`	Retrieves unvalidated referer from the ‘_wp_http_referer’ URL query variable or the HTTP referer.
esc_attr_x()`wp-includes/l10n.php`	Translates string with gettext context, and escapes it for safe use in an attribute.
wp_rand()`wp-includes/pluggable.php`	Generates a random non-negative number.
site_url()`wp-includes/link-template.php`	Retrieves the URL for the current site where WordPress application files (e.g. wp-blog-header.php or the wp-admin/ folder) are accessible.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
esc_url()`wp-includes/formatting.php`	Checks and cleans a URL.
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_post()`wp-includes/post.php`	Retrieves post data given a post ID or post object.

Show 6 more Show less

Used by	Description
get_the_content()`wp-includes/post-template.php`	Retrieves the post content.

Changelog

Version	Description
1.0.0	Introduced.

User Contributed Notes

Skip to note 2 content

wplmillet

6 years ago

Example:

add_filter( 'the_password_form', 'wporg_password_form' );
function wporg_password_form() {
    global $post;
    $label = 'pwbox-' . ( empty( $post->ID ) ? rand() : $post->ID );
    $output = '<form action="' . esc_url( site_url( 'wp-login.php?action=postpass', 'login_post' ) ) . '" class="post-password-form" method="post">
    ' . esc_html__( 'New Text for my protected post', 'text-domain' ) . '
    <label class="pass-label" for="' . $label . '">' . esc_html__( 'Password:', 'text-domain' ) . ' </label><input name="post_password" id="' . $label . '" type="password" size="20" style="background: #ffffff; border:1px solid #999; color:#333333; padding:10px;" size="20" /><input type="submit" name="Submit" class="button" value="' . esc_attr__( 'Submit', 'text-domain' ) . '" />
    </form><p class="text-below">' . esc_html__( 'Additional text to be placed below', 'text-domain' ) . '</p>
    ';
    return $output;
}

And you can use css like :

.text-below {
	color : red;
	font-size:14px;
	margin:0;
	padding:10px
}

and hide or modifiy label :

.pass-label {
display : none;
}

And adapt the button too : :

.button {
    background-color: #000;
    color:#fff;
    border: 0;
    margin: 0;
    height: 33px;
    padding: 0 6px 6px 6px;
    font-size: 15px;
}

云策 WordPress 开发者社区

函数文档

get_the_password_form()

概述

关键要点

代码示例

注意事项

Parameters

Return

Source

Hooks

Changelog

User Contributed Notes

函数文档

概述

关键要点

代码示例

注意事项

Parameters

Return

Source

Hooks

Related

Changelog

User Contributed Notes