laravel-dashboard-development

Laravel Dashboard Development 是围绕 spatie/laravel-dashboard 包的一套开发指南，用于构建显示在壁挂屏幕上的实时仪表盘。该包使用 Livewire 4、Tailwind CSS 4（通过浏览器 CDN）和 CSS Grid 进行布局。

用途

spatie/laravel-dashboard 用于构建实时仪表盘，适合在壁挂屏幕上展示。开发者可以创建自定义磁贴（Tile），将不同数据源的信息以网格形式组合呈现。

主要能力

创建自定义磁贴

Livewire 组件：创建继承 BaseTileComponent 的 Livewire 组件。关键点包括：$position 从 BaseTileComponent 继承，不要添加或覆盖 mount()；#[Defer] 已继承，骨架加载通过 placeholder() 自动工作；除非有额外初始化，否则无需 mount() 方法。
Blade 视图：将磁贴内容包裹在 <x-dashboard-tile> 组件中，始终传递 :position。
注册组件：在服务提供者中使用 Livewire 注册组件。

数据存储与检索

使用 Tile 模型在请求之间持久化数据，通过 firstOrCreateForName 和 putData/getData 方法操作。

获取外部数据

创建 Artisan 命令从 API 获取数据，并在控制台内核或 routes/console.php 中调度执行。

仪表盘设置

定义路由返回仪表盘视图，在视图中使用 <x-dashboard> 组件并放置各磁贴，通过 position 属性指定网格位置。

网格定位

磁贴使用类似 Excel 的表示法：列用字母，行用数字。例如 a1 表示单格，a1:b2 表示 2x2 区域，a1:c1 表示跨列。网格根据使用的位置自动调整大小。

磁贴属性

<x-dashboard-tile> 组件接受以下属性：position（字符串，必填，网格位置）、refresh-interval（?int，默认 null，Livewire 轮询间隔秒数）、title（?string，默认 null，磁贴标题）、fade（bool，默认 true，底部边缘淡出内容）、show（bool，默认 true，显示/隐藏磁贴）。

主题

仪表盘提供适应浅色/深色模式的 Tailwind 颜色工具类，如 text-default、text-dimmed、text-invers、text-accent、bg-canvas、bg-tile、text-success、text-warning、text-error 等，可与任意 Tailwind 工具类配合使用。

主题配置在 config/dashboard.php 中设置：light/dark 为固定模式，device 跟随操作系统偏好，auto 根据日出日落自动切换（使用经纬度）。

自定义资源

通过 Dashboard 服务注册额外的脚本或样式表，支持外部 URL、内联脚本和内联样式。

网格模板工具类

仪表盘包含用于磁贴内部网格布局的 Tailwind 主题工具类，如 grid-cols-1-1、grid-cols-1-auto、grid-rows-1-1 等。

使用方式

按照上述步骤创建 Livewire 组件、Blade 视图并注册，然后通过 Artisan 命令获取数据并调度，最后在仪表盘视图中放置磁贴并设置位置。

适用场景

适合需要在壁挂屏幕上展示实时数据的场景，例如监控面板、信息展示屏等。

限制与注意事项

应继承 BaseTileComponent，而非直接继承 Livewire\Component。
始终向 <x-dashboard-tile> 传递 :position="$position"。
使用 Tile 模型进行数据持久化。
使用 text-default、text-dimmed 等主题感知颜色。
不要仅为位置添加 $position 属性或 mount()，因为它已继承。
不要向磁贴添加 #[Defer]，它已从 BaseTileComponent 继承。
不要在配置文件之外使用 env() 调用。
不要在磁贴中存储大型数据集，保持数据精简以实现快速渲染。