外观

修改Logo

默认情况下,Filament 会在你的后台面板中使用你的应用名作为 Logo。

你也可以创建 resources/views/vendor/filament/components/brand.blade.php 文件,用来自定义 logo:

<img src="{{ asset('/images/logo.svg') }}" alt="Logo" class="h-10">

暗黑模式

Filament 默认只包含明亮主题。但是,你也可以在配置文件中使用 dark_mode 设置,让用户可以自由切换到暗黑模式:

'dark_mode' => true,

当暗黑模式启用,后台面板会自动遵守系统的暗黑/明亮模式偏好。你也可以通过用户的下拉菜单按钮永久切换模式。

如果你使用自定义主题,请确保你的 tailwind.config.js 文件有 darkMode: 'class'设置。

请注意:在生产环境中启用暗黑模式之前,请完整测试你的后台面板 - 特别是第三方插件,因它们可能还未被测试到位。

当用户切换暗黑/明亮模式时,一个被称为 dark-mode-toggled 的浏览器事件被派发了。你可以对其进行监听:

<div
x-data="{ mode: 'light' }"
x-on:dark-mode-toggled.window="mode = $event.detail"
>
<span x-show="mode === 'light'">
Light mode
</span>
 
<span x-show="mode === 'dark'">
Dark mode
</span>
</div>

可折叠侧边栏

默认情况下,侧边栏只在移动端可折叠。你也可以让他在桌面端可折叠。

你先需要发布配置文件,才能使用这个特性。

在配置文件 config/filament.php 中,将 layouts.sidebar.is_collapsible_on_desktop 设置为 true:

'layout' => [
'sidebar' => [
'is_collapsible_on_desktop' => true,
],
],

创建主题

Filament 允许你通过编译自定义的样式表,替换默认样式,来改变UI中所使用字体和颜色方案。这个自定义的样式表叫做"主题"。

主题使用Tailwind CSS、Tailwind Typography 插件、AutoprefixerTippy.js。你可以通过 NPM 安装它们:

npm install tailwindcss @tailwindcss/forms @tailwindcss/typography autoprefixer tippy.js --save-dev

要安装 Tailwind,你要在项目的根目录中创建 tailwind.config.js 文件。最简单的做法是运行 npx tailwindcss init

tailwind.config.js 中,注册你安装好的插件,添加表单构造器使用的自定义颜色:

const colors = require('tailwindcss/colors')
 
module.exports = {
content: [
'./resources/**/*.blade.php',
'./vendor/filament/**/*.blade.php',
],
darkMode: 'class',
theme: {
extend: {
colors: {
danger: colors.rose,
primary: colors.blue,
success: colors.green,
warning: colors.yellow,
},
},
},
plugins: [
require('@tailwindcss/forms'),
require('@tailwindcss/typography'),
],
}

你可以指定自己的颜色,使之在整个后台面板中使用。

如果你使用 Vite 来编译资源,请在 vite.config.js 文件中,注册 filament.css 主题文件:

import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
 
export default defineConfig({
plugins: [
laravel({
input: [
// ...
'resources/css/filament.css',
],
// ...
}),
],
})

然后将 Tailwind 添加到 postcss.config.js 文件中:

module.exports = {
plugins: {
tailwindcss: {},
autoprefixer: {},
},
}

如果你使用的是 Mix 编译, 在 webpack.mix.js 文件中,以 PostCSS 插件的形式注册 Tailwind CSS:

const mix = require('laravel-mix')
 
mix.postCss('resources/css/filament.css', 'public/css', [
require('tailwindcss'),
])

/resources/css/filament.css 文件中,引入Filament vendor CSS:

@import '../../vendor/filament/filament/resources/css/app.css';

现在,你可以在服务提供者的 boot() 方法中注册主题文件:

use Filament\Facades\Filament;
use Illuminate\Foundation\Vite;
 
Filament::serving(function () {
// Using Vite
Filament::registerTheme(
app(Vite::class)('resources/css/filament.css'),
);
 
// Using Laravel Mix
Filament::registerTheme(
mix('css/filament.css'),
);
});

加载Google字体

如果你在 tailwind.config.js 中指定了自定义的字体,你可能需要通过 Google 字体将其引入。

要获取该特性,你需要发布配置文件

google_fonts 配置项设置为要加载的新的 Google 字体 URL:

'google_fonts' => 'https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,500;0,700;1,400;1,500;1,700&display=swap',

调整最大内容宽度

Filament 暴露了一个配置项,允许用户调整所有页面的最大内容宽度。

要使用这个特性,你必须先发布配置文件

config/filament.php 中,将 layouts.max_content_width 设置成 xl7xl 之间的值,或者没有最大宽度的 full :

'layout' => [
'max_content_width' => 'full',
],

默认值为 7xl.

你可以使用 $maxContentWidth 属性,重写后台面板指定页面的最大内容宽度。

protected ?string $maxContentWidth = 'full';

引入前端资源

你可以在服务提供者的 boot() 方法中使用 registerScripts()registerStyles() 方法,来注册你自己的 Javascript 脚本或者 CSS 样式。

use Filament\Facades\Filament;
 
Filament::registerScripts([
asset('js/my-script.js'),
]);
 
Filament::registerStyles([
'https://unpkg.com/tippy.js@6/dist/tippy.css',
asset('css/my-styles.css'),
]);

你也可以传 true 作为 registerScripte() 的参数,让这个脚本在 Filament 核心 Javascript 文件前加载。这对注册来自于 CDN 中的 Alpine.js 插件很有用:

Filament::registerScripts([
'https://cdn.jsdelivr.net/npm/@ryangjchandler/alpine-tooltip@0.x.x/dist/cdn.min.js',
], true);

自定义meta标签

你可以将自定义标签(如 <meta><link> )添加到 header 中,使用如下代码:

use Filament\Facades\Filament;
use Illuminate\Support\HtmlString;
 
Filament::pushMeta([
new HtmlString('<link rel="manifest" href="/site.webmanifest" />'),
]);

通知位置

Filament 允许自定义通知的显示位置。

config/filament.php 文件中,将 layouts.notifications.alignment 设置为 leftcenterright 中的任意值,将 layouts.notifications.vertical_alignment 设置为 topcenter 或者 bottom 中的任意值:

'layout' => [
'notifications' => [
'vertical_alignment' => 'top'
'alignment' => 'center',
],
],

渲染钩子

Filament 允许你在后台面板布局的诸多结点中渲染 Blade 模板内容。这对于整合像 wire-elements/modal这样的包很有用。

这里有一个例子,在服务提供者中整合了wire-elements/modal

use Filament\Facades\Filament;
use Illuminate\Support\Facades\Blade;
 
Filament::registerRenderHook(
'body.start',
fn (): string => Blade::render('@livewire(\'livewire-ui-modal\')'),
);

你也可以在文件中渲染视图内容:

use Filament\Facades\Filament;
use Illuminate\Contracts\View\View;
 
Filament::registerRenderHook(
'body.start',
fn (): View => view('impersonation-banner'),
);

可用的钩子包括:

  • body.start - 在 <body> 之后
  • body.end - 在 </body> 之前
  • head.start - 在 <head> 之后
  • head.end - 在 </head> 之前
  • content.start - 在页面内容之前
  • content.end - 在页面内容之后
  • footer.before - footer 之前
  • footer.start - footer 内容开始位置(footer 中间)
  • footer.end - footer 内容的结束位置(footer 中间)
  • sidebar.start - 在 sidebar 内容之前
  • sidebar.end - 在 sidebar 内容之后
  • scripts.start - 在脚本定义之前
  • scripts.end - 在脚本之后
  • styles.start - 在样式定义之前
  • styles.end - 在样式定义之后
  • global-search.start - 在 全局搜索输入框之前
  • global-search.end - 在 全局搜索输入框之后

需要帮助? 加入论坛 或者打开 GitHub讨论

喜欢Filament?

Filament 中文文档由 laravel-filament.cn 翻译整理。站长用爱发电,希望为英文阅读不畅的朋友提供快速掌握Filament框架的途径。文档的翻译,社区的运营维护都需要时间精力上的付出。如果文档社区使你受益,如果你想支持站长...

打赏