全局搜索 | DevRefinery

引言

全局搜索允许您在应用的任何位置搜索您的所有资源记录。

设置全局搜索结果标题

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

php

protected static ?string $recordTitleAttribute = 'title';

此属性用于检索该记录的搜索结果标题。

你的资源需要有一个编辑或查看页面，以便全局搜索结果能够链接到一个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;

将全局搜索移动到侧边栏

默认情况下，全局搜索字段位于顶部栏。如果顶部栏被禁用，它将被添加到侧边栏。

您可以通过向配置中的 globalSearch() 方法传递 position 参数，选择始终将其移动到侧边栏：

php

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

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

排序全局搜索结果

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

php

protected static ?int $globalSearchSort = 3;

现在，排序值较低的导航项将显示在排序值较高的导航项之前 - 顺序是升序。

禁用全局搜索

如上文所述, 一旦您为资源设置了标题属性, 全局搜索就会自动启用. 有时您可能希望指定标题属性, 但不启用全局搜索.

这可以通过禁用全局搜索来完成配置:

php

use Filament\Panel;

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

注册全局搜索键绑定

全局搜索字段可以使用键盘快捷键打开。要配置这些，请将 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;

引言

全局搜索允许您在应用的任何位置搜索您的所有资源记录。

设置全局搜索结果标题

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

php

protected static ?string $recordTitleAttribute = 'title';

此属性用于检索该记录的搜索结果标题。

你的资源需要有一个编辑或查看页面，以便全局搜索结果能够链接到一个URL，否则将不会为此资源返回任何结果。

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

php

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

自定义全局搜索结果URL

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 事件

php

use Filament\Actions\Action;

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

限制全局搜索结果的数量

默认情况下，全局搜索将为每个资源返回最多 50 个结果。您可以通过覆盖 $globalSearchResultsLimit 属性在资源标签上自定义此项：

php

protected static int $globalSearchResultsLimit = 20;

将全局搜索移动到侧边栏

默认情况下，全局搜索字段位于顶部栏。如果顶部栏被禁用，它将被添加到侧边栏。

您可以通过向配置中的 globalSearch() 方法传递 position 参数，选择始终将其移动到侧边栏：

php

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

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

排序全局搜索结果

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

php

protected static ?int $globalSearchSort = 3;

现在，排序值较低的导航项将显示在排序值较高的导航项之前 - 顺序是升序。

禁用全局搜索

如上文所述, 一旦您为资源设置了标题属性, 全局搜索就会自动启用. 有时您可能希望指定标题属性, 但不启用全局搜索.

这可以通过禁用全局搜索来完成配置:

php

use Filament\Panel;

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

注册全局搜索键绑定

全局搜索字段可以使用键盘快捷键打开。要配置这些，请将 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() 方法对其进行自定义。

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

禁用搜索词拆分

php

protected static ?bool $shouldSplitGlobalSearchTerms = false;

文档导航

引言

设置全局搜索结果标题

跨多列全局搜索

为全局搜索结果添加额外细节

自定义全局搜索结果URL

将操作添加到全局搜索结果

从全局搜索操作中打开 URL

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

限制全局搜索结果的数量

将全局搜索移动到侧边栏

排序全局搜索结果

禁用全局搜索

注册全局搜索键绑定

配置全局搜索防抖

配置全局搜索字段后缀

禁用搜索词拆分

引言

设置全局搜索结果标题

跨多列全局搜索

为全局搜索结果添加额外细节

自定义全局搜索结果URL

将操作添加到全局搜索结果

从全局搜索操作中打开 URL

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

限制全局搜索结果的数量

将全局搜索移动到侧边栏

排序全局搜索结果

禁用全局搜索

注册全局搜索键绑定

配置全局搜索防抖

配置全局搜索字段后缀

禁用搜索词拆分