Question

wp_add_dashboard_widget( string $widget_id,  string $widget_name,  callable $callback,  callable $control_callback = null,  array $callback_args = null )

Adds a new dashboard widget.

---

description

---

参数

$widget_id

(string) (Required) Widget ID (used in the 'id' attribute for the widget).

$widget_name

(string) (Required) Title of the widget.

$callback

(callable) (Required) Function that fills the widget with the desired content. The function should echo its output.

$control_callback

(callable) (Optional) Function that outputs controls for the widget.

Default value: null

$callback_args

(array) (Optional) Data that should be set as the $args property of the widget array (which is the second parameter passed to your callback).

Default value: null

---

源代码

File: wp-admin/includes/dashboard.php

function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = null ) {
	$screen = get_current_screen();
	global $wp_dashboard_control_callbacks;

	$private_callback_args = array( '__widget_basename' => $widget_name );

	if ( is_null( $callback_args ) ) {
		$callback_args = $private_callback_args;
	} else if ( is_array( $callback_args ) ) {
		$callback_args = array_merge( $callback_args, $private_callback_args );
	}

	if ( $control_callback && current_user_can( 'edit_dashboard' ) && is_callable( $control_callback ) ) {
		$wp_dashboard_control_callbacks[$widget_id] = $control_callback;
		if ( isset( $_GET['edit'] ) && $widget_id == $_GET['edit'] ) {
			list($url) = explode( '#', add_query_arg( 'edit', false ), 2 );
			$widget_name .= ' <span class="postbox-title-action"><a href="' . esc_url( $url ) . '">' . __( 'Cancel' ) . '</a></span>';
			$callback = '_wp_dashboard_control_callback';
		} else {
			list($url) = explode( '#', add_query_arg( 'edit', $widget_id ), 2 );
			$widget_name .= ' <span class="postbox-title-action"><a href="' . esc_url( "$url#$widget_id" ) . '" class="edit-box open-box">' . __( 'Configure' ) . '</a></span>';
		}
	}

	$side_widgets = array( 'dashboard_quick_press', 'dashboard_primary' );

	$location = 'normal';
	if ( in_array($widget_id, $side_widgets) )
		$location = 'side';

	$priority = 'core';
	if ( 'dashboard_browser_nag' === $widget_id )
		$priority = 'high';

	add_meta_box( $widget_id, $widget_name, $callback, $screen, $location, $priority, $callback_args );
}

---

更新日志

Version	description
2.7.0	Introduced.

---

相关函数

Uses

• wp-admin/includes/screen.php: get_current_screen()
• wp-admin/includes/template.php: add_meta_box()
• wp-includes/capabilities.php: current_user_can()
• wp-includes/l10n.php: __()
• wp-includes/formatting.php: esc_url()
• wp-includes/functions.php: add_query_arg()
Show 1 more use Hide more uses

---

Used By

• wp-admin/includes/dashboard.php: wp_dashboard_setup()

---

User Contributed Notes

1. Skip to note content 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 Contributed by Codex

   Adding dashboard widgets
   Here is a simple dashboard widget:

   
   /**
    * Add a new dashboard widget.
    */
   function wpdocs_add_dashboard_widgets() {
   	wp_add_dashboard_widget( 'dashboard_widget', 'Example Dashboard Widget', 'dashboard_widget_function' );
   }
   add_action( 'wp_dashboard_setup', 'wpdocs_add_dashboard_widgets' );
   
   /**
    * Output the contents of the dashboard widget
    */
   function dashboard_widget_function( $post, $callback_args ) {
   	esc_html_e( "Hello World, this is my first Dashboard Widget!", "textdomain" );
   }
   
   

Running dashboard widgets
To run the function use this code:

do_action( 'wp_dashboard_setup' );

Adding widgets onto the side
The function doesn’t allow you to choose where you want your widget to go and will automatically add it to the “core” which is the left side. However you are able to get it on the right side very easily.

You can use the add_meta_box() function instead of wp_add_dashboard_widget. Simply specify ‘dashboard’ in place of the $post_type. For example:

add_meta_box( 'id', 'Dashboard Widget Title', 'dash_widget', 'dashboard', 'side', 'high' );