Mary UI：在 Laravel + Livewire 中用 daisyUI 构建 Blade 组件的实践指南

Mary UI 是一套为 Livewire 3 打造的 Laravel Blade 组件库，组件样式完全构建于 daisyUI 与 Tailwind CSS 之上，本身不携带任何自定义 CSS。这篇指南基于 daisyUI 仓库中的官方博客文档整理而成，面向正在使用 Laravel 与 Livewire 的开发者：读完你将理解 Mary UI 的设计理念与组件形态，并能在全新或已有 Laravel 项目中按两种路径完成安装接入，最终在 Blade 文件里用 Livewire 语法直接拼装出完整的 daisyUI 风格界面。

什么是 Mary UI？

Mary UI 是一组专门为 Livewire 3 制作的 Laravel Blade 组件（Blade components），构建在 daisyUI 与 Tailwind CSS 之上。如果你既是 Laravel 开发者又在使用 Livewire，Mary UI 的价值在于：把常见 UI 交互（表单、弹窗、按钮、表格、导航等）封装成开箱即用的 <x-*> 组件，让你更快、更省力地搭建页面。

Mary UI 与 daisyUI 的关系有两个关键事实：

1. Mary UI 不发布任何自定义 CSS，开箱即用的外观完全由 daisyUI 和 Tailwind 提供。这也是其体积与接入成本极低的原因——你不需要为 Mary UI 单独引入样式文件。
2. 组件样式可以覆盖：由于底层就是 daisyUI + Tailwind 的类名，你可以通过内联覆写 daisyUI 与 Tailwind 的 class 来定制绝大多数组件的样式（例如把一个按钮从默认外观改成主色按钮，只需追加 btn-primary 这类类名）。

换句话说，Mary UI 做的事情是"组件的 HTML 与逻辑封装层"，而"外观层"是 daisyUI。因此，Mary UI 能直接受益于 daisyUI 组件体系的所有能力。这一点在 daisyUI 源码中可以得到印证：Mary UI 复用的那些核心外观都来自 daisyUI 各组件样式文件，例如 button.css 中的 .btn、.btn-primary，input.css 中的 .input，以及 modal.css 中的 .modal-box 等类。只要这些类能正常产出（即 daisyUI 正确接入），Mary UI 组件便自动获得完整外观。

Mary UI 长什么样？一个表单示例

Mary UI 允许你在 Laravel 的 Blade 文件中，用 Livewire 语法直接使用 daisyUI 风格的组件。

下面这段代码（节选自 mary-ui/+page.md/blog/(posts)/mary-ui/+page.md)）演示了如何在 Blade 里写出一个完整表单——包含文本输入、带货币前缀的金额输入（自动处理金额格式化、提交未掩码值）以及按钮操作区：

<x-form wire:submit="save">
  <x-input label="Name" wire:model="name" />
  <x-input
    label="Amount"
    wire:model="amount"
    prefix="USD"
    money
    hint="It submits an unmasked value" />
  <x-slot:actions>
    <x-button label="Cancel" />
    <x-button label="Click me!" class="btn-primary" type="submit" spinner="save" />
  </x-slot:actions>
</x-form>

这段示例反映了 Mary UI 组件的几个典型特性，逐一看能帮助你理解它的设计思路：

• <x-form wire:submit="save">：表单容器组件，wire:submit 是 Livewire 的提交钩子，提交时触发 Livewire 组件里的 save() 方法。
• <x-input label="Name" wire:model="name" />：文本输入组件，label 生成输入框文字标签，wire:model 把输入双向绑定到 Livewire 属性 name。
• <x-input ... prefix="USD" money hint="...">：金额输入组件。money 开启金额格式化（如千分位、小数点），prefix="USD" 在输入框前显示货币前缀，而 hint 显示的辅助文案明确提示：表单提交的是未掩码（unmasked）的原始值——也就是说，用户看到的格式化文案与真正提交给后端的数值是解耦的，这避免了"提交带货币符号的脏数据"这一常见坑。
• <x-slot:actions>：具名插槽，把操作按钮放进表单的固定行为区。
• <x-button label="Cancel" /> 与 <x-button label="Click me!" class="btn-primary" type="submit" spinner="save" />：按钮组件。注意第二个按钮叠加了 class="btn-primary"——这正是上文所说"内联覆写 daisyUI 类"的体现，把按钮切换为 daisyUI 的主色按钮样式；spinner="save" 则会在对应 Livewire 请求进行中（save 方法执行期间）让按钮自动展示加载动画。

可以看到：写 UI 的行为变成了"用属性声明式地组装组件"，重复的表单样板代码被显著压缩。

在新 Laravel 项目中安装 Mary UI

如果是从零开始的 Laravel 项目，安装过程非常简短，核心只有三步。

第一步：用 Composer 安装 Mary UI 包

composer require robsontenorio/mary

第二步：执行官方一键安装命令

php artisan mary:install

该 Artisan 命令会帮你完成 Tailwind、daisyUI 及相关脚手架在项目中的接线工作，省去手工改配置的步骤。

第三步：启动开发服务器

yarn dev

开发服务器启动后，你便可以在 Blade 文件中直接使用 Mary UI 组件。这套流程之所以简洁，是因为 Mary UI 依赖 daisyUI 出样式，而一键安装命令已经把 daisyUI 接入了项目。

在已有 Laravel 项目中安装 Mary UI

对于已经存在的 Laravel 项目，安装链路更细，需要手动补全 Tailwind、daisyUI、Livewire 布局模板与 Vite 的接线。原文给出的步骤如下。

第 1 步：安装 Composer 包

composer require robsontenorio/mary

第 2 步：安装 Tailwind CSS、daisyUI 并初始化 Tailwind 配置文件

由于已有项目没有现成的 Tailwind 环境，需要一并装好工具链并生成配置文件：

yarn add -D tailwindcss daisyui@latest postcss autoprefixer && npx tailwindcss init -p

-D 表示全部作为开发依赖安装；npx tailwindcss init -p 会同时生成 tailwind.config.js 与 postcss.config.js。

第 3 步：修改 tailwind.config.js

必须让 Tailwind 扫描到 Mary UI 的 Blade 组件源码目录，否则组件中的 daisyUI 类名不会被生成：

export default {
  content: [
    // You will probably also need those lines
    "./resources/**/**/*.{js,blade.php}",
    "./app/View/Components/**/**/*.php",
    "./app/Livewire/**/**/*.php",

    // Add mary
    "./vendor/robsontenorio/mary/src/View/Components/**/*.php",
  ],

  // Add daisyUI
  plugins: [require("daisyui")],
}

这里的要点有两处：一是 content 中除了项目自身的模板与 Livewire/View 组件目录，必须追加 ./vendor/robsontenorio/mary/src/View/Components/**/*.php，否则 Tailwind 无法感知 Mary UI 内部使用的类名；二是通过 plugins: [require("daisyui")] 把 daisyUI 作为 Tailwind 插件载入。

第 4 步：在 resources/css/app.css 中添加 Tailwind 指令

@tailwind base;
@tailwind components;
@tailwind utilities;

第 5 步：生成 Livewire 默认布局模板

php artisan livewire:layout

该命令会创建 views/components/layouts/app.blade.php，作为 Livewire 页面共用的应用布局。

第 6 步：在默认布局模板中挂载 Vite

编辑上一步生成的 views/components/layouts/app.blade.php，在 <head> 中引入编译后的样式与脚本入口：

<head>
  ...
  <!-- This -->
  @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

<body>
  ...
</body>

第 7 步：启动开发服务器

yarn dev

完成以上全部步骤后，daisyUI 的类会被正确编译输出，你就能在任何 Blade 文件中直接使用 Mary UI 组件了。

版本背景：这篇文章对应的 daisyUI 形态与当前仓库的差异

需要说明的是，上述安装说明撰写于 2023 年 9 月，对应的是当时以 Tailwind CSS v3 + tailwind.config.js 配置 + require("daisyui") 插件为特征的接入方式。而本仓库当前维护的 daisyUI 5 已经迁移到 Tailwind CSS v4 的 CSS-first 体系，接入方式完全不同。

如果你在当前版本下新建 Laravel 项目，推荐直接参考仓库内的 daisyUI for Laravel 安装文档/docs/install/laravel/+page.md)。daisyUI 5 的方式不再需要 tailwind.config.js，而是在 CSS 入口文件里用 @import、@source 与 @plugin 指令声明一切，例如在 resources/css/app.css 中写入：

@import "tailwindcss";

@source "../**/*.blade.php";
@source "../**/*.js";
@source "../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php";
@source "../../storage/framework/views/*.php";

@plugin "daisyui";

随后分别运行 php artisan serve 与 npm run dev 即可。

两种方式的底层诉求是一致的：让 Tailwind 扫描到所有会使用 daisyUI 类名的模板文件，并确保 daisyUI 的插件/编译逻辑被启用。无论是 v3 的 content + plugins，还是 v4 的 @source + @plugin，都是在解决"哪个目录里会出现类名"以及"daisyUI 样式如何注入"这两个问题。对于已有项目接入 Mary UI，建议以你实际使用的 Tailwind 主版本对应方式为准，并把 Mary UI 的 Blade 组件目录（vendor/robsontenorio/mary 下的视图与 PHP 组件文件）纳入扫描范围。

小结

Mary UI 是一个典型的"daisyUI 生态组件层"项目：它把 Laravel Blade + Livewire 的开发体验与 daisyUI 的样式体系衔接起来，让表单、按钮等高频 UI 通过声明式 <x-*> 组件快速产出，同时因为不携带自有 CSS，样式上始终与 daisyUI 保持同源、可覆写。本文覆盖了它的设计理念、组件用法示例，以及新老 Laravel 项目两条完整的接入路径；无论你走哪条路径，最终在 Blade 中使用 Mary UI 组件的体验是一致的——所见即所得的 daisyUI 外观，加上 Livewire 驱动的交互逻辑。如果你想了解 daisyUI 本身的组件能力边界（例如 .btn-primary、.input、.modal-box 等类背后还有哪些变体），可以进一步阅读本仓库 daisyui/src/components 下的组件样式源码。