云策 WordPress 开发者社区

函数文档

wp_edit_posts_query()

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

概述

wp_edit_posts_query() 函数用于在编辑文章页面执行查询以获取文章列表。它处理查询参数、文章状态和分页设置，并返回查询文章类型的所有可用状态数组。

关键要点

  • 函数参数 $q 可选，默认为 $_GET 超全局变量，用于构建查询。
  • 返回值为字符串数组，包含查询文章类型的所有状态。
  • 内部处理包括设置文章类型、状态、排序、分页和粘性文章等查询参数。
  • 使用 wp() 函数执行查询，并返回可用状态数组。

代码示例

function wp_edit_posts_query( $q = false ) {
    if ( false === $q ) {
        $q = $_GET;
    }

    $q['m']   = isset( $q['m'] ) ? (int) $q['m'] : 0;
    $q['cat'] = isset( $q['cat'] ) ? (int) $q['cat'] : 0;

    $post_statuses = get_post_stati();

    if ( isset( $q['post_type'] ) && in_array( $q['post_type'], get_post_types(), true ) ) {
        $post_type = $q['post_type'];
    } else {
        $post_type = 'post';
    }

    $avail_post_stati = get_available_post_statuses( $post_type );
    $post_status      = '';
    $perm             = '';

    if ( isset( $q['post_status'] ) && in_array( $q['post_status'], $post_statuses, true ) ) {
        $post_status = $q['post_status'];
        $perm        = 'readable';
    }

    $orderby = '';

    if ( isset( $q['orderby'] ) ) {
        $orderby = $q['orderby'];
    } elseif ( isset( $q['post_status'] ) && in_array( $q['post_status'], array( 'pending', 'draft' ), true ) ) {
        $orderby = 'modified';
    }

    $order = '';

    if ( isset( $q['order'] ) ) {
        $order = $q['order'];
    } elseif ( isset( $q['post_status'] ) && 'pending' === $q['post_status'] ) {
        $order = 'ASC';
    }

    $per_page       = "edit_{$post_type}_per_page";
    $posts_per_page = (int) get_user_option( $per_page );
    if ( empty( $posts_per_page ) || $posts_per_page < 1 ) {
        $posts_per_page = 20;
    }

    $posts_per_page = apply_filters( 'edit_posts_per_page', $posts_per_page, $post_type );
    $posts_per_page = apply_filters( "edit_{$post_type}_per_page", $posts_per_page );

    $query = array(
        'post_type'      => $post_type,
        'post_status'    => $post_status,
        'perm'           => $perm,
        'orderby'        => $orderby,
        'order'          => $order,
        'posts_per_page' => $posts_per_page,
    );

    if ( is_post_type_hierarchical( $post_type ) && empty( $orderby ) ) {
        $query['orderby'] = 'menu_order title';
        $query['order']   = 'asc';
        $query['posts_per_page'] = -1;
        $query['posts_per_page'] = -1;
        $query['ignore_sticky_posts'] = true;
    }

    if ( ! empty( $q['show_sticky'] ) ) {
        $query['post__in'] = (array) get_option( 'sticky_posts' );
    }

    wp( $query );

    return $avail_post_stati;
}

注意事项

  • 函数使用 apply_filters() 钩子允许自定义每页显示的文章数量，包括通用和特定文章类型的过滤器。
  • 相关函数包括 get_available_post_statuses()、wp()、get_user_option() 等，用于支持查询和状态管理。
  • 自 WordPress 2.5.0 版本引入，主要用于 WP_Posts_List_Table::prepare_items() 方法。
📄 原文内容

Runs the query to fetch the posts for listing on the edit posts page.

Parameters

$qarray|falseoptional
Array of query variables to use to build the query.
Defaults to the $_GET superglobal.

Default:false

Return

string[] An array of all the statuses for the queried post type.

Source

function wp_edit_posts_query( $q = false ) {
	if ( false === $q ) {
		$q = $_GET;
	}

	$q['m']   = isset( $q['m'] ) ? (int) $q['m'] : 0;
	$q['cat'] = isset( $q['cat'] ) ? (int) $q['cat'] : 0;

	$post_statuses = get_post_stati();

	if ( isset( $q['post_type'] ) && in_array( $q['post_type'], get_post_types(), true ) ) {
		$post_type = $q['post_type'];
	} else {
		$post_type = 'post';
	}

	$avail_post_stati = get_available_post_statuses( $post_type );
	$post_status      = '';
	$perm             = '';

	if ( isset( $q['post_status'] ) && in_array( $q['post_status'], $post_statuses, true ) ) {
		$post_status = $q['post_status'];
		$perm        = 'readable';
	}

	$orderby = '';

	if ( isset( $q['orderby'] ) ) {
		$orderby = $q['orderby'];
	} elseif ( isset( $q['post_status'] ) && in_array( $q['post_status'], array( 'pending', 'draft' ), true ) ) {
		$orderby = 'modified';
	}

	$order = '';

	if ( isset( $q['order'] ) ) {
		$order = $q['order'];
	} elseif ( isset( $q['post_status'] ) && 'pending' === $q['post_status'] ) {
		$order = 'ASC';
	}

	$per_page       = "edit_{$post_type}_per_page";
	$posts_per_page = (int) get_user_option( $per_page );
	if ( empty( $posts_per_page ) || $posts_per_page < 1 ) {
		$posts_per_page = 20;
	}

	/**
	 * Filters the number of items per page to show for a specific 'per_page' type.
	 *
	 * The dynamic portion of the hook name, `$post_type`, refers to the post type.
	 *
	 * Possible hook names include:
	 *
	 *  - `edit_post_per_page`
	 *  - `edit_page_per_page`
	 *  - `edit_attachment_per_page`
	 *
	 * @since 3.0.0
	 *
	 * @param int $posts_per_page Number of posts to display per page for the given post
	 *                            type. Default 20.
	 */
	$posts_per_page = apply_filters( "edit_{$post_type}_per_page", $posts_per_page );

	/**
	 * Filters the number of posts displayed per page when specifically listing "posts".
	 *
	 * @since 2.8.0
	 *
	 * @param int    $posts_per_page Number of posts to be displayed. Default 20.
	 * @param string $post_type      The post type.
	 */
	$posts_per_page = apply_filters( 'edit_posts_per_page', $posts_per_page, $post_type );

	$query = compact( 'post_type', 'post_status', 'perm', 'order', 'orderby', 'posts_per_page' );

	// Hierarchical types require special args.
	if ( is_post_type_hierarchical( $post_type ) && empty( $orderby ) ) {
		$query['orderby']                = 'menu_order title';
		$query['order']                  = 'asc';
		$query['posts_per_page']         = -1;
		$query['posts_per_archive_page'] = -1;
		$query['fields']                 = 'id=>parent';
	}

	if ( ! empty( $q['show_sticky'] ) ) {
		$query['post__in'] = (array) get_option( 'sticky_posts' );
	}

	wp( $query );

	return $avail_post_stati;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘edit_posts_per_page’, int $posts_per_page, string $post_type )

Filters the number of posts displayed per page when specifically listing “posts”.

apply_filters( “edit_{$post_type}_per_page”, int $posts_per_page )

Filters the number of items per page to show for a specific ‘per_page’ type.

Uses Description
get_available_post_statuses()wp-admin/includes/post.php

Returns all the possible statuses for a post type.
wp()wp-includes/functions.php

Sets up the WordPress query.
get_user_option()wp-includes/user.php

Retrieves user option that can be either per Site or per Network.
get_post_stati()wp-includes/post.php

Gets a list of post statuses.
is_post_type_hierarchical()wp-includes/post.php

Determines whether the post type is hierarchical.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
get_option()wp-includes/option.php

Retrieves an option value based on an option name.
get_post_types()wp-includes/post.php

Gets a list of all registered post type objects.

Show 3 moreShow less

Used by Description
WP_Posts_List_Table::prepare_items()wp-admin/includes/class-wp-posts-list-table.php

Changelog

Version Description
2.5.0 Introduced.