Blade 与 HTML
Blade 组件与纯 HTML 是什么关系 — 如实说明哪些是自动的、哪些是手动的。
结论: 一个方向自动，另一个方向手动
Blade → HTML 是自动且始终准确的。 Blade 组件在服务器上渲染为纯 HTML。本站每个组件页面的 HTML 标签页，都是 Blade 标签页代码的实际渲染输出 — 绝非手工转写，因此不可能与真实输出产生偏差。
不存在 HTML → Blade 的自动转换工具。 把现有 HTML 替换为 Blade 组件是手动工作（见下方步骤）。所谓“可互转”只在类名词汇层面成立 — 在标记结构层面，转换是单向的。
文档双标签页的原理
每个组件页面的“用法”区块都有 Blade / HTML 两个标签页。HTML 标签页由 Blade::render() 现场生成，因此库升级后文档中的 HTML 也不会过时。下面是嵌入本页的实例:
复制
已复制
<x-button color="primary" icon="rocket">Launch</x-button>
加载中…
无法加载 HTML
只使用 HTML 一侧（不用 Blade 的项目）
HTML 标签页的输出是纯 HTML 加类名字符串，可以复制到不使用 Blade 的项目中。需要两样东西:
- 编译好的 CSS — 这些类引用主题令牌（bg-primary 等）与调音令牌（p-md、var(--radius-box) 等）。目前官方分发只有 Composer 包构建；独立的 CSS 包（npm）正在准备中。
- Alpine.js — 动态组件（modal / tabs / dropdown 等）的 HTML 输出原样包含 x-data 属性。页面加载 Alpine.js（+ @alpinejs/focus / @alpinejs/collapse）后，复制的 HTML 即可直接工作。静态组件（button / badge / card 等）完全不需要 JS。
反方向: 把现有 HTML 迁移到 Blade
没有自动转换器，但步骤很简单:
- 在组件目录的预览中找到最接近的组件 — 组件目录 →
- 复制该页面 Blade 标签页的最小示例，对齐 props（color / size / appearance 等）
- 丢掉手写的类名堆 — 颜色、形状、间距交给主题与调音
相反的方向 — 离开 Blade 回到纯 Tailwind — 有官方工具: php artisan ui:eject 会把 pinion-ui 类批量改写为重现所选主题 × 调音外观的原生 Tailwind（不锁定的逃生舱）。
哪些组件需要 Alpine
静态（无需 JS）
button / badge / card / avatar / input / checkbox / progress / tooltip / breadcrumb / stat / timeline / stepper 等
动态（需要 Alpine）
modal / tabs / accordion / dropdown / popover / sidebar / select / alert(dismissible) / notification / collapse 等
常见问题
类名字符串与结构可以原样使用（只要加载了 CSS，外观即可重现）。但 x-data 的交互属于 Alpine，在 React / Vue 中需要移植到各框架的状态管理。官方的多框架支持计划以 Web Components 形式提供。
都没有 — 它没有被固化。输出类是语义令牌（bg-primary、p-md 等），会跟随目标页面的 data-theme / data-tune。
能。页面上展示的每个示例都经过实际渲染验证 — HTML 标签页就是证据；渲染失败的示例根本无法出现在页面上。