Filament 中文文档

主题

全部文档

概览 ​

简介 ​

通知通过流式 API 构建的 Notification 对象发送。在 Notification 对象上调用 send() 会派发通知并在应用中展示。由于使用 session 闪存通知，可从代码任意位置发送，包括 JavaScript，不仅限于 Livewire 组件。

php
<?php

namespace App\Livewire;

use Filament\Notifications\Notification;
use Livewire\Component;

class EditPost extends Component
{
    public function save(): void
    {
        // ...

        Notification::make()
            ->title('Saved successfully')
            ->success()
            ->send();
    }
}
成功通知成功通知

设置标题 ​

通知的主要信息显示在标题中。可如下设置标题：

php
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->send();

标题文本可包含基础、安全的 HTML 元素。要用 Markdown 生成安全 HTML，可使用 Str::markdown() 辅助函数：title(Str::markdown('Saved **successfully**'))

DANGER

Filament 内置 HTML 清理器允许内联 style 属性，以支持字体颜色、文本高亮、图片尺寸等富文本格式功能。这意味着 background: url(...) 或 position: fixed 等 CSS 属性不会从已清理的 HTML 中剥离。若内容来自不可信用户，应考虑收紧默认配置。如何自定义清理器详见安全文档。

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .send()

设置图标 ​

可选地，通知可带有显示在内容前方的图标。也可为图标设置颜色，默认为灰色：

php
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->icon('heroicon-o-document-text')
    ->iconColor('success')
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .icon('heroicon-o-document-text')
    .iconColor('success')
    .send()
带图标的通知带图标的通知

通知常有 success、warning、danger 或 info 等状态。不必手动设置对应的图标与颜色，可用 status() 方法传入状态。也可改用专用的 success()、warning()、danger() 与 info() 方法。因此，上面示例可简化为：

php
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .send()
各种状态的通知各种状态的通知

设置背景色 ​

通知默认无背景色。可通过如下方式设置颜色，为通知提供更多上下文：

php
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->color('success')
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .color('success')
    .send()
带背景色的通知带背景色的通知

设置持续时间 ​

默认情况下，通知显示 6 秒后自动关闭。可如下以毫秒指定自定义持续时间：

php
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->duration(5000)
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .duration(5000)
    .send()

若更希望以秒而非毫秒设置持续时间，可以这样做：

php
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->seconds(5)
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .seconds(5)
    .send()

你可能希望某些通知不自动关闭，而需用户手动关闭。可通过将通知设为持久化实现：

php
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->persistent()
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .persistent()
    .send()

设置正文文本 ​

额外通知文本可在 body() 中展示：

php
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->body('Changes to the post have been saved.')
    ->send();

正文文本可包含基础、安全的 HTML 元素。要用 Markdown 生成安全 HTML，可使用 Str::markdown() 辅助函数：body(Str::markdown('Changes to the **post** have been saved.'))

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .body('Changes to the post have been saved.')
    .send()
带正文的通知带正文的通知

为通知添加操作 ​

通知支持 Actions，即渲染在通知内容下方的按钮。可打开 URL 或派发 Livewire 事件。操作可如下定义：

php
use Filament\Actions\Action;
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->body('Changes to the post have been saved.')
    ->actions([
        Action::make('view')
            ->button(),
        Action::make('undo')
            ->color('gray'),
    ])
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .body('Changes to the post have been saved.')
    .actions([
        new FilamentNotificationAction('view')
            .button(),
        new FilamentNotificationAction('undo')
            .color('gray'),
    ])
    .send()
带操作的通知带操作的通知

关于如何为操作按钮设置样式，详见此处。

从通知操作打开 URL ​

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

php
use Filament\Actions\Action;
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->body('Changes to the post have been saved.')
    ->actions([
        Action::make('view')
            ->button()
            ->url(route('posts.show', $post), shouldOpenInNewTab: true),
        Action::make('undo')
            ->color('gray'),
    ])
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .body('Changes to the post have been saved.')
    .actions([
        new FilamentNotificationAction('view')
            .button()
            .url('/view')
            .openUrlInNewTab(),
        new FilamentNotificationAction('undo')
            .color('gray'),
    ])
    .send()

DANGER

若将用户可控数据传给 url() 方法，应验证 URL 未使用 javascript: 或 data: 等危险协议。否则可能使应用面临 XSS 攻击。最简单的防护是用 Filament 的 Str::sanitizeUrl() 辅助函数包装该值；对未使用 http/https（或相对路径）的 URL，它会返回 null。

从通知操作派发 Livewire 事件 ​

有时希望在点击通知操作时执行额外代码。可通过设置点击操作时要派发的 Livewire 事件实现。可选传入数据数组，会作为参数出现在 Livewire 组件的事件监听器中：

php
use Filament\Actions\Action;
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->body('Changes to the post have been saved.')
    ->actions([
        Action::make('view')
            ->button()
            ->url(route('posts.show', $post), shouldOpenInNewTab: true),
        Action::make('undo')
            ->color('gray')
            ->dispatch('undoEditingPost', [$post->id]),
    ])
    ->send();

也可使用 dispatchSelf 与 dispatchTo：

php
Action::make('undo')
    ->color('gray')
    ->dispatchSelf('undoEditingPost', [$post->id])

Action::make('undo')
    ->color('gray')
    ->dispatchTo('another_component', 'undoEditingPost', [$post->id])

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .body('Changes to the post have been saved.')
    .actions([
        new FilamentNotificationAction('view')
            .button()
            .url('/view')
            .openUrlInNewTab(),
        new FilamentNotificationAction('undo')
            .color('gray')
            .dispatch('undoEditingPost'),
    ])
    .send()

同样，也提供 dispatchSelf 与 dispatchTo：

js
new FilamentNotificationAction('undo')
    .color('gray')
    .dispatchSelf('undoEditingPost')

new FilamentNotificationAction('undo')
    .color('gray')
    .dispatchTo('another_component', 'undoEditingPost')

从操作关闭通知 ​

从操作打开 URL 或派发事件后，可能希望立即关闭通知：

php
use Filament\Actions\Action;
use Filament\Notifications\Notification;

Notification::make()
    ->title('Saved successfully')
    ->success()
    ->body('Changes to the post have been saved.')
    ->actions([
        Action::make('view')
            ->button()
            ->url(route('posts.show', $post), shouldOpenInNewTab: true),
        Action::make('undo')
            ->color('gray')
            ->dispatch('undoEditingPost', [$post->id])
            ->close(),
    ])
    ->send();

或使用 JavaScript：

js
new FilamentNotification()
    .title('Saved successfully')
    .success()
    .body('Changes to the post have been saved.')
    .actions([
        new FilamentNotificationAction('view')
            .button()
            .url('/view')
            .openUrlInNewTab(),
        new FilamentNotificationAction('undo')
            .color('gray')
            .dispatch('undoEditingPost')
            .close(),
    ])
    .send()

使用 JavaScript 对象 ​

JavaScript 对象（FilamentNotification 与 FilamentNotificationAction）会赋值给 window.FilamentNotification 与 window.FilamentNotificationAction，因此可在页面脚本中使用。

也可在打包的 JavaScript 文件中导入它们：

js
import { Notification, NotificationAction } from '../../vendor/filament/notifications/dist/index.js'

// ...

用 JavaScript 关闭通知 ​

通知发送后，可通过在 window 上派发名为 close-notification 的浏览器事件按需关闭。

事件需包含所发送通知的 ID。可用 Notification 对象上的 getId() 方法获取 ID：

php
use Filament\Notifications\Notification;

$notification = Notification::make()
    ->title('Hello')
    ->persistent()
    ->send()

$notificationId = $notification->getId()

要从 Livewire 关闭通知，可派发该事件：

php
$this->dispatch('close-notification', id: $notificationId);

或从 JavaScript（本例为 Alpine.js）：

blade
<button x-on:click="$dispatch('close-notification', { id: notificationId })" type="button">
    Close Notification
</button>

若能获取并持久化通知 ID，再用它关闭通知，这是推荐做法，因为 ID 唯一生成，不会误关其他通知。但若无法持久化随机 ID，可在发送通知时传入自定义 ID：

php
use Filament\Notifications\Notification;

Notification::make('greeting')
    ->title('Hello')
    ->persistent()
    ->send()

此时可通过派发带自定义 ID 的事件关闭通知：

blade
<button x-on:click="$dispatch('close-notification', { id: 'greeting' })" type="button">
    Close Notification
</button>

请注意，若用同一 ID 发送多条通知，可能出现意外副作用，因此推荐使用随机 ID。

定位通知 ​

可在服务提供者或中间件中调用 Notifications::alignment() 与 Notifications::verticalAlignment() 配置通知对齐。可传入 Alignment::Start、Alignment::Center、Alignment::End、VerticalAlignment::Start、VerticalAlignment::Center 或 VerticalAlignment::End：

php
use Filament\Notifications\Livewire\Notifications;
use Filament\Support\Enums\Alignment;
use Filament\Support\Enums\VerticalAlignment;

Notifications::alignment(Alignment::Start);
Notifications::verticalAlignment(VerticalAlignment::End);
定位在页面底部起始处的通知定位在页面底部起始处的通知