云策 WordPress 开发者社区

钩子文档

user_search_columns

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

概述

user_search_columns 过滤器用于自定义 WP_User_Query 搜索时查询的数据库字段列。默认搜索列包括 ID、user_login、user_email、user_url、user_nicename 和 display_name，开发者可以通过此过滤器调整搜索范围。

关键要点

  • 过滤器名称：user_search_columns，在 WP_User_Query 的 prepare_query() 方法中调用。
  • 参数：接收三个参数：$search_columns（要搜索的字段数组）、$search（搜索词）、$query（WP_User_Query 实例）。
  • 返回值：过滤器函数必须返回修改后的 $search_columns 数组，否则搜索条件可能为空。
  • 函数命名：过滤器函数名需唯一，避免与其他已声明函数冲突。
  • 版本历史：自 WordPress 3.6.0 引入。

代码示例

// 示例1：添加 user_url 字段到搜索列
add_filter( 'user_search_columns', 'wpdocs_filter_function_name', 10, 3 );

function wpdocs_filter_function_name( $search_columns, $search, $wp_user_query ) {
    $search_columns[] = 'user_url';
    return $search_columns;
}
// 示例2：根据搜索词动态调整搜索列（如包含 '.com' 时仅搜索 user_url）
add_filter( 'user_search_columns', 'wpdocs_filter_function_name', 10, 2 );

function wpdocs_filter_function_name( $search_columns, $search ) {
    $val = strpos( $search, '.com' );
    
    if ( false !== $val ) {
        $search_columns = array( 'user_url' );
    }
    
    return $search_columns;
}
📄 原文内容

Filters the columns to search in a WP_User_Query search.

Description

The default columns depend on the search term, and include ‘ID’, ‘user_login’, ‘user_email’, ‘user_url’, ‘user_nicename’, and ‘display_name’.

Parameters

$search_columnsstring[]
Array of column names to be searched.
$searchstring
Text being searched.
$queryWP_User_Query
The current WP_User_Query instance.

More Information

The user_search_columns filter is used to determine which user fields in the database are used when performing a search on user information.

When the ‘user_search_columns’ filter is called, it is passed three parameters: an array of fields to search, the search term, WP_User_Query object

<pre>add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );

function filter_function_name( $search_columns, $search, $wp_user_query ) {
// Alter $search_columns to include the fields you want to search on
return $search_columns;
}

Where ‘filter_function_name’ is the function WordPress should call when the filter is run. Note that the filter function must return a value after it is finished processing or the search terms will be empty.

filter_function_name should be unique function name. It cannot match any other function name already declared

Source

$search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this );

View all references View on Trac View on GitHub

Used by Description
WP_User_Query::prepare_query()wp-includes/class-wp-user-query.php

Prepares the query variables.

Changelog

Version Description
3.6.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    Collins Mbaka


    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

    Add a field to search on

    In this example, the user’s URL is also added to the list of columns searched

    add_filter( 'user_search_columns', 'wpdocs_filter_function_name', 10, 3 );
    
function wpdocs_filter_function_name( $search_columns, $search, $wp_user_query ) {
    $search_columns[] = 'user_url';
    return $search_columns;
}

  2. Skip to note 6 content


    Collins Mbaka


    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

    Alter search fields based on the search term

    In this example, if the user searches for something with ‘.com’ in it only the user_url field will be searched

    add_filter( 'user_search_columns', 'wpdocs_filter_function_name', 10, 2 );

function wpdocs_filter_function_name( $search_columns, $search ) {
    $val = strpos( $search, '.com' );
    
    if ( false !== $val ) {
	    $search_columns = array( 'user_url' );
    }
    
    return $search_columns;
}

  3. Skip to note 7 content


    Akira Tachibana


    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

    (From Codex)
    Add a field to search on
    In this example the user’s URL is also added to the list of columns searched

    add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );
    
function filter_function_name( $search_columns, $search, $wp_user_query ) {
    $search_columns[] = 'user_url';
    return $search_columns;
}

  4. Skip to note 8 content


    Akira Tachibana


    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

    (From Codex)
    Alter search fields based on search term

    In this example if the user searches for something with ‘.com’ in it only the user_url field will be searched.

    add_filter( 'user_search_columns', 'filter_function_name', 10, 3 );

function filter_function_name( $search_columns, $search, $wp_user_query ) {
    $val = strpos($search, '.com');
    
    if( $val !== false ) {
	    $search_columns = array('user_url');
    }
    
    return $search_columns;
}