函数文档

maintenance_nag()

💡 云策文档标注

概述

maintenance_nag() 函数用于在 WordPress 后台显示维护提醒的 HTML 消息,主要针对自动更新失败的情况。它检查全局变量和站点选项,以确定是否需要显示提醒,并根据用户权限输出相应的警告信息。

关键要点

  • 函数返回 void 或 false,当不需要显示提醒时返回 false。
  • 通过检查全局变量 $upgrading 和站点选项 'auto_core_update_failed' 来判断更新状态。
  • 使用 version_compare() 比较失败尝试的版本与当前 WordPress 版本,以决定是否显示提醒。
  • 根据 current_user_can('update_core') 权限,为不同用户显示不同的消息内容。
  • 调用 wp_admin_notice() 函数输出带有特定类和类型的警告通知。

代码示例

if ( current_user_can( 'update_core' ) ) {
    $msg = sprintf(
        __( 'An automated WordPress update has failed to complete - please attempt the update again now.' ),
        'update-core.php'
    );
} else {
    $msg = __( 'An automated WordPress update has failed to complete! Please notify the site administrator.' );
}

wp_admin_notice(
    $msg,
    array(
        'type'               => 'warning',
        'additional_classes' => array( 'update-nag', 'inline' ),
        'paragraph_wrap'     => false,
    )
);

注意事项

  • 此函数在 WordPress 2.7.0 版本中引入,用于处理核心自动更新失败后的用户通知。
  • 提醒消息的显示逻辑依赖于 'auto_core_update_failed' 选项,该选项在成功更新后会被 Core_Upgrader 清除。
  • 函数内部使用了多个核心函数,如 wp_get_wp_version()、get_site_option() 等,确保在调用前这些函数可用。

📄 原文内容

Displays maintenance nag HTML message.

Return

void|false

Source

function maintenance_nag() {
	global $upgrading;

	$nag = isset( $upgrading );

	if ( ! $nag ) {
		$failed = get_site_option( 'auto_core_update_failed' );
		/*
		 * If an update failed critically, we may have copied over version.php but not other files.
		 * In that case, if the installation claims we're running the version we attempted, nag.
		 * This is serious enough to err on the side of nagging.
		 *
		 * If we simply failed to update before we tried to copy any files, then assume things are
		 * OK if they are now running the latest.
		 *
		 * This flag is cleared whenever a successful update occurs using Core_Upgrader.
		 */
		$comparison = ! empty( $failed['critical'] ) ? '>=' : '>';
		if ( isset( $failed['attempted'] ) && version_compare( $failed['attempted'], wp_get_wp_version(), $comparison ) ) {
			$nag = true;
		}
	}

	if ( ! $nag ) {
		return false;
	}

	if ( current_user_can( 'update_core' ) ) {
		$msg = sprintf(
			/* translators: %s: URL to WordPress Updates screen. */
			__( 'An automated WordPress update has failed to complete - <a href="%s">please attempt the update again now</a>.' ),
			'update-core.php'
		);
	} else {
		$msg = __( 'An automated WordPress update has failed to complete! Please notify the site administrator.' );
	}

	wp_admin_notice(
		$msg,
		array(
			'type'               => 'warning',
			'additional_classes' => array( 'update-nag', 'inline' ),
			'paragraph_wrap'     => false,
		)
	);
}

Changelog

Version Description
2.7.0 Introduced.