README

全局搜索模态框是一个强大的可定制全局搜索插件，灵感来源于Algolia搜索模态框，通过跟踪收藏夹、每个面板中您在Filament应用程序中的最近搜索以及突出显示等功能，增强了默认的搜索功能。

功能

强大的模态框
固有的Filament设计标准
跟踪最近搜索
跟踪收藏搜索
突出显示搜索查询
自定义空查询、页脚和未找到结果视图
配置搜索项的树形视图
搜索建议
自定义查询构建器
语音搜索
渲染钩子

屏幕截图

活动搜索示例

浅色模式

深色模式

空查询字符串

浅色模式

深色模式

例如，当Filament的灰色设置为板岩色时

社区反馈

在filamentdaily频道上观看视频

需求

由于这个pull request，需要Filament v3.2.93或更高版本。

安装

按照以下步骤在您的Filament应用程序中安装全局搜索模态框插件

本指南提供了有关安装和使用此插件的详细说明。如果您有任何疑问、遇到错误、需要支持或希望提交功能请求，请随时通过charrafimedfilament@gmail.com与我联系。

    composer require charrafimed/global-search-modal

配置

每个面板的插件

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
        ])
}

就是这样，如果您在面板中启用了全局搜索，那么您将获得完整的体验

⚠️ 警告：本地存储和URL持久性

如果您在本地开发并经常刷新或重新种植数据库，请注意，最近搜索功能会将数据持久化到本地存储。如果基础数据（如ID或别名）已更改，这可能导致使用过时的URL。

解决方案

为确保在重新种植或刷新数据后使用正确的URL，请手动清除浏览器本地存储。这将强制应用程序根据更新的数据构建新的URL。

在生产环境中，这个问题不应该发生，因为数据不会频繁刷新或重新种植。

自定义模态行为

通过逃脱关闭

默认情况下，此插件启用通过逃脱关闭，如果您想自定义通过逃脱关闭的行为，可以这样做

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->closeByEscaping(enabled: false)
        ])
}

通过点击外部关闭

默认情况下，此插件启用通过点击外部关闭的模态框，如果您想自定义通过点击关闭的行为，可以这样做

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->closeByClickingAway(enabled: false)
        ])
}

关闭按钮

默认情况下，该插件不包含关闭按钮。要添加关闭按钮

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->closeButton(enabled: true)
        ])
}

在移动端可切换

要禁用在移动端滑动关闭

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->SwappableOnMobile(enabled: false)
        ])
}

模态滑动覆盖

默认情况下，此插件将模态框居中，但如果您想使此模态框滑动覆盖，可以这样做

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->slideOver()
        ])
}

最大宽度

默认情况下，此插件包含一个最大宽度为2xl（对应Tailwind标准）的模态框。但是，如果您想自定义模态框的最大宽度，可以这样做：您可以使用filament核心命名空间下的Filament\Support\Enums\MaxWidth中的maxWidth枚举值。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
use Filament\Support\Enums\MaxWidth;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->maxWidth(MaxWidth::TwoExtraLarge) // for example 
        ])
}

available options are :
    - ExtraSmall
    - Small
    - Medium
    - Large
    - ExtraLarge
    - TwoExtraLarge
    - ThreeExtraLarge
    - FourExtraLarge
    - FiveExtraLarge
    ...

模态框位置

全局搜索模态框插件允许您使用position方法自定义模态框的位置。您可以通过指定顶部、右部、左部、右部、左部和底部的值来定义模态框的位置。该方法支持两种指定位置的格式：带有单位的数值和带有单位的字符串。

示例：自定义位置

要自定义模态框的位置，请在GlobalSearchModalPlugin实例中使用position方法。您可以使用top和right方法分别指定顶部和底部值。两种支持的格式为：

带有单位的数值：使用数值后跟单位来指定位置（例如，100, 'px'）。
带有单位的字符串：直接以字符串形式指定位置（例如，"30px"）。

使用示例

以下是如何自定义模态框位置的示例

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
use CharrafiMed\GlobalSearchModal\Customization\Position;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
        GlobalSearchModalPlugin::make()
            ->position(
                fn (Position $position) => $position
                    ->top(100, 'px')     // Numeric value with unit
                    ->right('30rem')     // String with unit
            )
    ]);
}

两种格式都受支持，并且可以根据您的偏好互换使用。

提示：此方法使用原生CSS样式，因此您可以与任何浮点值一起使用任何CSS单位。

高亮显示

您可以使用->highlighter()方法启用或禁用查询匹配的高亮显示。默认情况下，高亮显示是启用的。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->highlighter(false) // disable highlighting
        ]);
}

传递样式

要自定义高亮文本的样式，您可以使用highlightQueryStyles方法。此方法接受一个字符串或一个样式数组。

使用数组示例

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->highlightQueryStyles([
                    'background-color' => 'yellow',
                    'font-weight' => 'bold',
                ])
        ]);
}

使用原始字符串示例

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                    ->highlightQueryStyles('background-color: yellow; font-weight: bold;') // Custom styles

        ]);
}

本地存储

全局搜索模态框插件包括与本地存储交互的功能。这使得插件能够保留最近的搜索和收藏的搜索，并将搜索项组织到组中。以下是CanInteractWithLocalStorage特性提供的方法及其使用方法。

允许的最大项目数

默认情况下，它跟踪10个收藏和10个最近的项。您可以使用localStorageMaxItemsAllowed方法设置本地存储中允许的最大项目数。此方法接受一个整数。注意例如，如果您设置为8，则允许本地存储中最多8个项目，并跟踪8个最近的搜索。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->localStorageMaxItemsAllowed(20) // sets maximum items to 50
        ]);
}

保留收藏的最近搜索

您可以使用RetainRecentIfFavorite方法启用或禁用如果标记为收藏则保留最近搜索的功能。换句话说，如果尝试将最近的搜索标记为收藏，则它将从最近搜索中删除。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->RetainRecentIfFavorite(true) // enables retention of recent searches if they are favorites
        ]);
}

将项目与其组关联

您可以使用associateItemsWithTheirGroups方法启用将项目与其组关联的功能。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->associateItemsWithTheirGroups() // enables association of items with groups
        ]);
}

动画

此插件使用alpine-animation包提供无缝的DOM更改，如果您觉得这个插件有帮助，请考虑在GitHub上给它一个⭐！

自定义视图

全局搜索模态框插件提供了一些自定义视图选项，允许您创建更个性化的搜索体验。以下是插件提供的方法及其使用方法。

启用页脚视图

您可以使用keepFooterView方法移除页脚视图。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->keepFooterView(false) // Enables the footer view
        ]);
}

自定义页脚视图

您可以使用footerView方法设置自定义页脚视图。此方法接受一个视图实例。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
use Illuminate\Support\Facades\View;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->footerView(View::make('custom-footer-view')) // or the view helper method view 
        ]);
}

它默认会查找resources/views，如果您想使用自定义命名空间，可以指定后缀，如下所示。

GlobalSearchModalPlugin::make()
                ->footerView(View::make('namespace::custom-footer-view'))

自定义未找到视图

您可以使用notFoundResultsView方法为找不到搜索结果设置自定义视图。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
use Illuminate\Support\Facades\View;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->notFoundResultsView(View::make('custom-not-found-view'))
        ]);
}

自定义空查询视图

您可以使用emptyQueryView方法为空搜索查询设置自定义视图。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;
use Illuminate\Support\Facades\View;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->emptyQueryView(View::make('custom-empty-query-view')) // Sets a custom empty query view
        ]);
}

占位符

您可以使用插件提供的placeholder方法自定义搜索输入框的占位符文本。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->placeholder('Type to search...')      
        ]);
}

搜索项树形图标

您可以配置是否在左侧显示搜索结果的树形图标。以下示例演示了如何启用或禁用此功能。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->searchItemTree(false)
        ]);
}

展开的URL目标

您可以配置结果区域是否完全可点击或仅限于标题区域。以下示例演示了如何启用或禁用此功能。

use CharrafiMed\GlobalSearchModal\GlobalSearchModalPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            GlobalSearchModalPlugin::make()
                ->expandedUrlTarget(enabled: true)
        ]);
}

添加对新语言的支持

任何人都可以简单地将插件添加对母语的支持。如果您的期望语言尚未提供，您可以轻松地通过以下步骤进行贡献

添加新语言的步骤

导航到resources/lang/目录。这是所有语言文件存储的地方。
为lang创建一个新JSON语言文件，如es.json。在新创建的JSON文件中，为以下所需字符串提供翻译

  {
  "Please enter a search term to get started.": "Por favor, ingrese un término de búsqueda para comenzar.",
  "to select": "para seleccionar",
  "to navigate": "para navegar",
  "to close": "para cerrar",
  "Search for anything ...": "Buscar cualquier cosa ...",
  "favorite this item": "Agregar este elemento a favoritos",
  "delete": "eliminar",
  "recent": "reciente",
  "favorites": "favoritos"
}

无障碍访问

即将推出

charrafimed / global-search-modal

维护者

详情

README

功能

屏幕截图

活动搜索示例

浅色模式

深色模式

空查询字符串

浅色模式

深色模式

例如，当Filament的灰色设置为板岩色时

社区反馈

需求

安装

配置

每个面板的插件

⚠️ 警告：本地存储和URL持久性

解决方案

自定义模态行为

通过逃脱关闭

通过点击外部关闭

关闭按钮

在移动端可切换

模态滑动覆盖

最大宽度

模态框位置

示例：自定义位置

使用示例

高亮显示

传递样式

使用数组示例

使用原始字符串示例

本地存储

允许的最大项目数

保留收藏的最近搜索

将项目与其组关联

动画

自定义视图

启用页脚视图

自定义页脚视图

自定义未找到视图

自定义空查询视图

占位符

搜索项树形图标

展开的URL目标

添加对新语言的支持

添加新语言的步骤

无障碍访问