云策 WordPress 开发者社区

函数文档

wp_list_sort()

查看官方原文 ↗
💡 云策文档标注

概述

wp_list_sort() 是一个 WordPress 函数，用于对对象或数组的列表进行排序。它基于一个或多个排序参数，支持升序或降序排列，并可选择是否保留原始键名。

关键要点

  • 函数接受一个数组作为输入，可以是对象数组或关联数组。
  • 排序参数 $orderby 可以是字符串（单个字段）或数组（多个字段），默认值为空数组。
  • 排序方向 $order 可以是 'ASC'（升序）或 'DESC'（降序），仅在 $orderby 为字符串时使用，默认值为 'ASC'。
  • 参数 $preserve_keys 控制是否保留输入数组的键名，默认值为 false（不保留）。
  • 函数返回排序后的数组，如果输入不是数组，则返回空数组。
  • 内部使用 WP_List_Util 类实现排序逻辑。

代码示例

$animals = [
	'alligator' => [ 'name' => 'alligator', 'fly' => false, 'class' => 'reptile' ],
	'dog'       => [ 'name' => 'dog',       'fly' => false, 'class' => 'mammal' ],
	'cat'       => [ 'name' => 'cat',       'fly' => false, 'class' => 'mammal' ],
	'falcon'    => [ 'name' => 'falcon',    'fly' => true,  'class' => 'bird' ],
	'bat'       => [ 'name' => 'bat',       'fly' => true,  'class' => 'mammal' ],
];

wp_list_sort( $animals, 'class' );
// 按 'class' 字段排序，不保留键名

wp_list_sort( $animals, 'name', 'DESC' );
// 按 'name' 字段降序排序，不保留键名

wp_list_sort( $animals, 'name', 'ASC', true );
// 按 'name' 字段升序排序，并保留键名
📄 原文内容

Sorts an array of objects or arrays based on one or more orderby arguments.

Parameters

$input_listarrayrequired
An array of objects or arrays to sort.
$orderbystring|arrayoptional
Either the field name to order by or an array of multiple orderby fields as $orderby => $order.

Default:array()

$orderstringoptional
Either 'ASC' or 'DESC'. Only used if $orderby is a string. Default 'ASC'.
$preserve_keysbooloptional
Whether to preserve keys.

Default:false

Return

array The sorted array.

Source

function wp_list_sort( $input_list, $orderby = array(), $order = 'ASC', $preserve_keys = false ) {
	if ( ! is_array( $input_list ) ) {
		return array();
	}

	$util = new WP_List_Util( $input_list );

	return $util->sort( $orderby, $order, $preserve_keys );
}

View all references View on Trac View on GitHub

Uses Description
WP_List_Util::__construct()wp-includes/class-wp-list-util.php

Constructor.
Used by Description
WP_Sitemaps_Posts::get_url_list()wp-includes/sitemaps/providers/class-wp-sitemaps-posts.php

Gets a URL list for a post type sitemap.
WP_Customize_Nav_Menu_Setting::filter_wp_get_nav_menus()wp-includes/customize/class-wp-customize-nav-menu-setting.php

Filters the wp_get_nav_menus() result to ensure the inserted menu object is included, and the deleted one is removed.
WP_Customize_Nav_Menu_Item_Setting::sort_wp_get_nav_menu_items()wp-includes/customize/class-wp-customize-nav-menu-item-setting.php

Re-apply the tail logic also applied on $items by wp_get_nav_menu_items() .
WP_Customize_Manager::prepare_controls()wp-includes/class-wp-customize-manager.php

Prepares panels, sections, and controls.
get_permalink()wp-includes/link-template.php

Retrieves the full permalink for the current post or post ID.
wp_get_nav_menu_items()wp-includes/nav-menu.php

Retrieves all menu items of a navigation menu.

Show 1 moreShow less

Changelog

Version Description
4.7.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Felipe Elia


    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    Example of usage:

    $animals = [
	'alligator' => [ 'name' => 'alligator', 'fly' => false, 'class' => 'reptile' ],
	'dog'       => [ 'name' => 'dog',       'fly' => false, 'class' => 'mammal' ],
	'cat'       => [ 'name' => 'cat',       'fly' => false, 'class' => 'mammal' ],
	'falcon'    => [ 'name' => 'falcon',    'fly' => true,  'class' => 'bird' ],
	'bat'       => [ 'name' => 'bat',       'fly' => true,  'class' => 'mammal' ],
];

wp_list_sort( $animals, 'class' );
// [
//   0 => [ 'name' => 'falcon', ... ]
//   1 => [ 'name' => 'cat', ... ]
//   2 => [ 'name' => 'dog', ... ]
//   3 => [ 'name' => 'bat', ... ]
//   4 => [ 'name' => 'alligator', ... ]
// ]

wp_list_sort( $animals, 'name', 'DESC' );
// [
//   0 => [ 'name' => 'falcon', ... ]
//   1 => [ 'name' => 'dog', ... ]
//   2 => [ 'name' => 'cat', ... ]
//   3 => [ 'name' => 'bat', ... ]
//   4 => [ 'name' => 'alligator', ... ]
// ]

wp_list_sort( $animals, 'name', 'ASC', true );
// [
//   'alligator' => [ 'name' => 'alligator', ... ]
//   'bat'       => [ 'name' => 'bat', ... ]
//   'cat'       => [ 'name' => 'cat', ... ]
//   'dog'       => [ 'name' => 'dog', ... ]
//   'falcon'    => [ 'name' => 'falcon', ... ]
// ]