全局搜索 - 面板构建器

概述

全局搜索允许你在应用的任何地方搜索所有的资源记录。

设置全局搜索结果标题

要在模型中启用全局搜索，你必须先为资源设置一个 title 属性：

protected static ?string $recordTitleAttribute = 'title';
protected static ?string $recordTitleAttribute = 'title';

这一属性用于检索搜索记录结果的标题。

你的资源中需要有编辑页或查看页，这样全局搜索结果才可以链接到对应页面，否则不会返回该资源的结果。

你可以重写 getGlobalSearchResultTitle() 方法进一步自定义标题。它将返回普通文本字符串，或者 Illuminate\Support\HtmlString 或 Illuminate\Contacts\Support\Htmlable 实例。这就允许你在搜索结果标题中渲染 HTML 或者 Markdown。

use Illuminate\Contracts\Support\Htmlable;
 
public static function getGlobalSearchResultTitle(Model $record): string | Htmlable
{
    return $record->name;
}
use Illuminate\Contracts\Support\Htmlable;

public static function getGlobalSearchResultTitle(Model $record): string | Htmlable
{
    return $record->name;
}

多字段搜索

如果你想要在资源中搜索多个字段，你可以重写 getGloballySearchableAttributes() 方法。“点语法”让你可以搜索关联的内部:

public static function getGloballySearchableAttributes(): array
{
    return ['title', 'slug', 'author.name', 'category.name'];
}
public static function getGloballySearchableAttributes(): array
{
    return ['title', 'slug', 'author.name', 'category.name'];
}

添加额外详情到全局搜索结果

搜索结果可以在标题的下面显示“详情(Details)”，让用户获取更多记录信息。要启用此特性，你必须重写 getGlobalSearchResultDetails() 方法：

public static function getGlobalSearchResultDetails(Model $record): array
{
    return [
        'Author' => $record->author->name,
        'Category' => $record->category->name,
    ];
}
public static function getGlobalSearchResultDetails(Model $record): array
{
    return [
        'Author' => $record->author->name,
        'Category' => $record->category->name,
    ];
}

此例中，记录的分类和作者会显示在搜索结果的标题下面。不过，category 和 author 关联是通过懒加载实现，会导致搜索结果的性能不佳。想要积极加载这些关联，必须重写 getGlobalSearchEloquentQuery() 方法：

public static function getGlobalSearchEloquentQuery(): Builder
{
    return parent::getGlobalSearchEloquentQuery()->with(['author', 'category']);
}
public static function getGlobalSearchEloquentQuery(): Builder
{
    return parent::getGlobalSearchEloquentQuery()->with(['author', 'category']);
}

自定义全局搜索结果 URL

全局搜索结果会链接到资源的编辑页，或者在用户没有编辑权限时链接到查看页。你可以重写 getGlobalSearchResultUrl() 方法并返回你想使用的路由，进行自定义：

public static function getGlobalSearchResultUrl(Model $record): string
{
    return UserResource::getUrl('edit', ['record' => $record]);
}
public static function getGlobalSearchResultUrl(Model $record): string
{
    return UserResource::getUrl('edit', ['record' => $record]);
}

添加 Action 到全局搜索结果

全局搜索支持 Action，将其在每个搜索结果中渲染成按钮。籍此可以打开一个网址或者发起一个 Livewire 事件。

Action 可以定义如下：

use Filament\GlobalSearch\Actions\Action;
 
public static function getGlobalSearchResultActions(Model $record): array
{
    return [
        Action::make('edit')
            ->url(static::getUrl('edit', ['record' => $record])),
    ];
}
use Filament\GlobalSearch\Actions\Action;

public static function getGlobalSearchResultActions(Model $record): array
{
    return [
        Action::make('edit')
            ->url(static::getUrl('edit', ['record' => $record])),
    ];
}

了解更多 Action 按钮样式请点击此处。

全局搜索 Action 中打开 URL

当点击 Action 时，你可以打开 URL(可选新标签页)：

use Filament\GlobalSearch\Actions\Action;
 
Action::make('view')
    ->url(static::getUrl('view', ['record' => $record]), shouldOpenInNewTab: true)
use Filament\GlobalSearch\Actions\Action;

Action::make('view')
    ->url(static::getUrl('view', ['record' => $record]), shouldOpenInNewTab: true)

全局搜索 Action 中发送 Livewire 事件

有时候，你希望在点击全局搜索结果 Action 时，执行额外的代码。通过设置点击 Action 时发送 Livewire 事件，可以达成该效果。你可以传入一个可选的数据数组，这个数组在 Livewire 组件的事件监听者中作为参数使用：

use Filament\GlobalSearch\Actions\Action;
 
Action::make('quickView')
    ->dispatch('quickView', [$record->id])
use Filament\GlobalSearch\Actions\Action;

Action::make('quickView')
    ->dispatch('quickView', [$record->id])

限制全局搜索结果的数量

默认情况下，全局搜索每个资源会返回多达 50 个结果。你可以重写资源标签上的 $globalSearchResultsLimit 属性对其自定义：

protected static int $globalSearchResultsLimit = 20;
protected static int $globalSearchResultsLimit = 20;

禁用全局搜索

如上所述，当你为资源设置 title 属性时，全局搜索会自动启用。而有时，你只想指定 title 属性而不想启用全局搜索。

为此，可以在配置中禁用全局搜索：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearch(false);
}
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearch(false);
}

注册全局搜索键盘绑定

全局搜索字段可以使用键盘快捷键打开。要设置此项，在配置中传入 globalSearchKeyBindings() 方法：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchKeyBindings(['command+k', 'ctrl+k']);
}
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchKeyBindings(['command+k', 'ctrl+k']);
}

配置全局搜索防抖动

全局搜索的默认防抖动时间为 500ms，以限制用户键入时发出的请求数量。你可以通过在配置中使用 globalSearchDebounce() 方法来对其进行修改：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchDebounce('750ms');
}
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchDebounce('750ms');
}

配置全局搜索字段后缀

全局搜索字段默认不包含任何后缀。你可以在配置的 globalSearchFieldSuffix() 对此进行自定义：

如果你想在后缀中显示当前配置的全局搜索键盘绑定，可以使用 globalSearchFieldKeyBindingSuffix() 方法，它会将第一个键盘绑定作为全局搜索字段的后缀进行显示：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchFieldKeyBindingSuffix();
}
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchFieldKeyBindingSuffix();
}

要自定义后缀，你可以将字符串或函数传入到 globalSearchFieldSuffix() 方法。比如，为每个平台手动提供自定义键盘绑定：

use Filament\Panel;
use Filament\Support\Enums\Platform;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchFieldSuffix(fn (): ?string => match (Platform::detect()) {
            Platform::Windows, Platform::Linux => 'CTRL+K',
            Platform::Mac => '⌘K',
            default => null,
        });
}
use Filament\Panel;
use Filament\Support\Enums\Platform;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchFieldSuffix(fn (): ?string => match (Platform::detect()) {
            Platform::Windows, Platform::Linux => 'CTRL+K',
            Platform::Mac => '⌘K',
            default => null,
        });
}

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion

#概述

#设置全局搜索结果标题

#多字段搜索

#添加额外详情到全局搜索结果

#自定义全局搜索结果 URL

#添加 Action 到全局搜索结果

#全局搜索 Action 中打开 URL

#全局搜索 Action 中发送 Livewire 事件

#限制全局搜索结果的数量

#禁用全局搜索

#注册全局搜索键盘绑定

#配置全局搜索防抖动

#配置全局搜索字段后缀

概述