Filament 中文文档

主题

全部文档

全局搜索 ​

简介 ​

全局搜索允许你在应用任意位置搜索所有资源记录。

全局搜索全局搜索

设置全局搜索结果标题 ​

要为模型启用全局搜索，必须为资源 设置标题属性：

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

该属性用于获取该记录的搜索结果标题。

WARNING

资源需要有编辑页或查看页，以便全局搜索结果能链接到 URL，否则该资源不会返回任何结果。

可通过覆盖 getGlobalSearchResultTitle() 方法进一步自定义标题。它可返回纯文本字符串，或 Illuminate\Support\HtmlString / Illuminate\Contracts\Support\Htmlable 实例。这样可在搜索结果标题中渲染 HTML，甚至 Markdown：

php
use Illuminate\Contracts\Support\Htmlable;

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

跨多列进行全局搜索 ​

若希望跨资源的多个列搜索，可覆盖 getGloballySearchableAttributes() 方法。「点记法」允许你搜索关联内部：

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

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

搜索结果可在标题下方显示「详情」，为用户提供更多记录信息。要启用此功能，必须覆盖 getGlobalSearchResultDetails() 方法：

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

在此例中，记录的分类与作者会显示在搜索结果标题下方。

带额外详情的全局搜索带额外详情的全局搜索

不过，category 与 author 关联会被懒加载，导致结果性能较差。要 预加载 这些关联，必须覆盖 getGlobalSearchEloquentQuery() 方法：

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

自定义全局搜索结果 URL ​

全局搜索结果会链接到资源的 编辑页；若用户没有 编辑权限，则链接到 查看页。要自定义，可覆盖 getGlobalSearchResultUrl() 并返回你选择的路由：

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

为全局搜索结果添加操作 ​

全局搜索支持操作，即渲染在每条搜索结果下方的按钮。它们可打开 URL 或派发 Livewire 事件。

可按如下方式定义操作：

php
use Filament\Actions\Action;

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

可在 此处 了解如何设置操作按钮样式。

带操作的全局搜索带操作的全局搜索

从全局搜索操作打开 URL ​

点击操作时可打开 URL，并可选择在新标签页中打开：

php
use Filament\Actions\Action;

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

从全局搜索操作派发 Livewire 事件 ​

有时希望在点击全局搜索结果操作时执行额外代码。可通过设置点击操作时派发的 Livewire 事件实现。也可选传入数据数组，这些数据会作为参数在 Livewire 组件的事件监听器中可用：

php
use Filament\Actions\Action;

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

限制全局搜索结果数量 ​

默认情况下，全局搜索每个资源最多返回 50 条结果。可通过覆盖 $globalSearchResultsLimit 属性自定义：

php
protected static int $globalSearchResultsLimit = 20;

排序全局搜索结果 ​

默认情况下，全局搜索结果按资源名称字母序排列。可在资源上设置 $globalSearchSort 属性自定义顺序：

php
protected static ?int $globalSearchSort = 3;

现在，排序值较小的导航项会出现在较大值之前——顺序为升序。

如 上文所述，一旦为资源设置标题属性，全局搜索会自动启用。有时你可能想指定标题属性却不启用全局搜索。

可在 配置 中禁用全局搜索：

php
use Filament\Panel;

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

默认情况下，所有带 标题属性 的资源都会出现在全局搜索结果中。若希望资源显式选择加入，可在 配置 中使用 globalSearchResourceOptIn() 方法：

php
use Filament\Panel;

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

现在，只有显式将 $isGloballySearchable 设为 true 的资源才会出现在全局搜索结果中：

php
protected static bool $isGloballySearchable = true;

未声明该属性的资源会被排除在全局搜索之外，即使已设置标题属性。

将全局搜索移至侧边栏 ​

默认情况下，全局搜索字段位于顶栏。若顶栏被禁用，则会加入侧边栏。

可通过在 配置 中向 globalSearch() 传入 position 参数，选择始终将其移至侧边栏：

php
use Filament\Enums\GlobalSearchPosition;
use Filament\Panel;

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

注册全局搜索快捷键 ​

可用键盘快捷键打开全局搜索字段。要配置它们，请在 配置 中使用 globalSearchKeyBindings() 方法：

php
use Filament\Panel;

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

配置全局搜索防抖 ​

全局搜索默认防抖时间为 500ms，以限制用户输入时的请求次数。可在 配置 中用 globalSearchDebounce() 方法更改：

php
use Filament\Panel;

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

配置全局搜索字段后缀 ​

全局搜索字段默认不包含后缀。可在 配置 中用 globalSearchFieldSuffix() 方法自定义。

若希望在后缀中显示当前配置的 全局搜索快捷键，可使用 globalSearchFieldKeyBindingSuffix() 方法，它会将第一个已注册快捷键显示为全局搜索字段的后缀：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->globalSearchFieldKeyBindingSuffix();
}
带快捷键后缀的全局搜索字段带快捷键后缀的全局搜索字段

若要自行自定义后缀，可向 globalSearchFieldSuffix() 传入字符串或函数。例如，为各平台手动提供自定义快捷键后缀：

php
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,
        });
}

禁用搜索词拆分 ​

默认情况下，全局搜索会将搜索词拆成单个词并分别搜索，使查询更灵活。但在大数据集时可能影响性能。可通过在资源上将 $shouldSplitGlobalSearchTerms 设为 false 禁用此行为：

php
protected static ?bool $shouldSplitGlobalSearchTerms = false;