公告: 旧版文档请移步 -> http://v2.laravel-filament.cn/docs

Languages

Version

Theme

面板构建器 - 资源

全局搜索

概述

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

设置全局搜索结果标题

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

protected static ?string $recordTitleAttribute = 'title';

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

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

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

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'];
}

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

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

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

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

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]);
}

添加 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])),
];
}

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

全局搜索 Action 中打开 URL

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

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])

限制全局搜索结果的数量

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

protected static int $globalSearchResultsLimit = 20;

禁用全局搜索

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

为此,可以在配置中禁用全局搜索:

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']);
}

配置全局搜索防抖动

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

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();
}

要自定义后缀,你可以将字符串或函数传入到 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,
});
}
Edit on GitHub

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

下一页
Widgets