Question

wp_page_menu( array|string $args = array() )

Displays or retrieves a list of pages with an optional home link.

---

description

The arguments are listed below and part of the arguments are for wp_list_pages()} function. Check that function for more info on those arguments.

---

参数

$args

(array|string) (Optional) Arguments to generate a page menu. See wp_list_pages() for additional arguments.

• 'sort_column'
  (string) How to short the list of pages. Accepts post column names. Default 'menu_order, post_title'.
• 'menu_id'
  (string) ID for the div containing the page list. Default is empty string.
• 'menu_class'
  (string) Class to use for the element containing the page list. Default 'menu'.
• 'container'
  (string) Element to use for the element containing the page list. Default 'div'.
• 'echo'
  (bool) Whether to echo the list or return it. Accepts true (echo) or false (return). Default true.
• 'show_home'
  (int|bool|string) Whether to display the link to the home page. Can just enter the text you'd like shown for the home link. 1|true defaults to 'Home'.
• 'link_before'
  (string) The HTML or text to prepend to $show_home text.
• 'link_after'
  (string) The HTML or text to append to $show_home text.
• 'before'
  (string) The HTML or text to prepend to the menu. Default is '<ul>'.
• 'after'
  (string) The HTML or text to append to the menu. Default is '</ul>'.
• 'item_spacing'
  (string) Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'. Default 'discard'.
• 'walker'
  (Walker) Walker instance to use for listing pages. Default empty (Walker_Page).

Default value: array()

---

返回值

(string|void) HTML menu

---

源代码

File: wp-includes/post-template.php

function wp_page_menu( $args = array() ) {
	$defaults = array(
		'sort_column'  => 'menu_order, post_title',
		'menu_id'      => '',
		'menu_class'   => 'menu',
		'container'    => 'div',
		'echo'         => true,
		'link_before'  => '',
		'link_after'   => '',
		'before'       => '<ul>',
		'after'        => '</ul>',
		'item_spacing' => 'discard',
		'walker'       => '',
	);
	$args = wp_parse_args( $args, $defaults );

	if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ) ) ) {
		// invalid value, fall back to default.
		$args['item_spacing'] = $defaults['item_spacing'];
	}

	if ( 'preserve' === $args['item_spacing'] ) {
		$t = "\t";
		$n = "\n";
	} else {
		$t = '';
		$n = '';
	}

	/**
	 * Filters the arguments used to generate a page-based menu.
	 *
	 * @since 2.7.0
	 *
	 * @see wp_page_menu()
	 *
	 * @param array $args An array of page menu arguments.
	 */
	$args = apply_filters( 'wp_page_menu_args', $args );

	$menu = '';

	$list_args = $args;

	// Show Home in the menu
	if ( ! empty($args['show_home']) ) {
		if ( true === $args['show_home'] || '1' === $args['show_home'] || 1 === $args['show_home'] )
			$text = __('Home');
		else
			$text = $args['show_home'];
		$class = '';
		if ( is_front_page() && !is_paged() )
			$class = 'class="current_page_item"';
		$menu .= '<li ' . $class . '><a href="' . home_url( '/' ) . '">' . $args['link_before'] . $text . $args['link_after'] . '</a></li>';
		// If the front page is a page, add it to the exclude list
		if (get_option('show_on_front') == 'page') {
			if ( !empty( $list_args['exclude'] ) ) {
				$list_args['exclude'] .= ',';
			} else {
				$list_args['exclude'] = '';
			}
			$list_args['exclude'] .= get_option('page_on_front');
		}
	}

	$list_args['echo'] = false;
	$list_args['title_li'] = '';
	$menu .= wp_list_pages( $list_args );

	$container = sanitize_text_field( $args['container'] );

	// Fallback in case `wp_nav_menu()` was called without a container.
	if ( empty( $container ) ) {
		$container = 'div';
	}

	if ( $menu ) {

		// wp_nav_menu doesn't set before and after
		if ( isset( $args['fallback_cb'] ) &&
			'wp_page_menu' === $args['fallback_cb'] &&
			'ul' !== $container ) {
			$args['before'] = "<ul>{$n}";
			$args['after'] = '</ul>';
		}

		$menu = $args['before'] . $menu . $args['after'];
	}

	$attrs = '';
	if ( ! empty( $args['menu_id'] ) ) {
		$attrs .= ' id="' . esc_attr( $args['menu_id'] ) . '"';
	}

	if ( ! empty( $args['menu_class'] ) ) {
		$attrs .= ' class="' . esc_attr( $args['menu_class'] ) . '"';
	}

	$menu = "<{$container}{$attrs}>" . $menu . "</{$container}>{$n}";

	/**
	 * Filters the HTML output of a page-based menu.
	 *
	 * @since 2.7.0
	 *
	 * @see wp_page_menu()
	 *
	 * @param string $menu The HTML output.
	 * @param array  $args An array of arguments.
	 */
	$menu = apply_filters( 'wp_page_menu', $menu, $args );
	if ( $args['echo'] )
		echo $menu;
	else
		return $menu;
}

---

更新日志

Version	description
4.7.0	Added the item_spacing argument.
4.4.0	Added menu_id, container, before, after, and walker arguments.
2.7.0	Introduced.

---

相关函数

Uses

• wp-includes/l10n.php: __()
• wp-includes/formatting.php: sanitize_text_field()
• wp-includes/formatting.php: esc_attr()
• wp-includes/query.php: is_front_page()
• wp-includes/query.php: is_paged()
• wp-includes/functions.php: wp_parse_args()
• wp-includes/link-template.php: home_url()
• wp-includes/plugin.php: apply_filters()
• wp-includes/option.php: get_option()
• wp-includes/post-template.php: wp_list_pages()
• wp-includes/post-template.php: wp_page_menu_args
• wp-includes/post-template.php: wp_page_menu
Show 7 more uses Hide more uses

---

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

   Display Home as a Page
   The following example causes “Home” to be added to the beginning of the list of pages displayed. In addition, the Pages wrapped in a div element, page IDs 5, 9, and 23, are excluded from the list of pages displayed, and the pages are listed in Page Order. The list is prefaced with the title “Page Menu”.

   
   <h2>Page Menu</h2>
   <?php wp_page_menu('show_home=1&exclude=5,9,23&menu_class=page-navi&sort_column=menu_order'); ?>
   

Display Home as a Page called Blog
The following example causes “Blog” (instead of “Home”) to be added to the beginning of the list of pages displayed:

<?php wp_page_menu( array( 'show_home' => 'Blog', 'sort_column' => 'menu_order' ) ); ?>

Display only Home
The following example displays just a link to “Home”. Note that the include=9999′ references a page ID that does not exist so only a link for Home is displayed.

<?php wp_page_menu('show_home=1&include=9999'); ?>