flux-ui

Flux UI（Vue 3）

Flux 是 Bas Milius 推出的观点鲜明的 Vue 3 组件库：从 @flux-ui/components 按名称导出（SFC、<script lang="ts" setup>），文档见 flux-ui.dev，其中的信息是 props、emits 和 slots 的准确信息来源。实际应用也会使用同系列的 @flux-ui/application（应用外壳）和 @flux-ui/statistics（KPI／图表）。

此技能是一个路由器。 它记录了经久耐用的判断（选用哪个组件、如何组合、命名陷阱），并将 props 表交由文档说明。请选择下面合适的参考文件；不要凭记忆查找准确的 props。

1. 消歧（请先阅读）

“Flux UI”可能指代多种项目。此技能仅适用于 basmilius/flux：Vue 3、npm @flux-ui/components，文档见 flux-ui.dev。请勿将其用于以下项目，也不要混用语法：

• livewire/flux（fluxui.dev）：采用 flux:button 样式标签的 Laravel/Livewire/Blade 工具包。这是另一个项目。
• Flux Web Components 库（j-flex、j-box 等）。这也是另一个项目。

在 Vue Flux 任务中输出 flux:button Blade 标签或 j- 元素，说明你混淆了库：请停止，并改用以 Flux 为前缀的 Vue 组件。

2. 设置（最容易悄悄导致构建失败的三项）

完整安装、Vite 预设、FluxRoot、图标和 tokens：请参阅 references/conventions.md。需要提前了解的陷阱：

• Vue 3.6 预发布版 peer 依赖。 Flux 3.x 不接受 vue@latest（3.5.x 无法满足 peer 依赖）。随着 3.6 接近稳定版，可接受的版本范围也会变化，因此请直接从软件包中读取（npm view @flux-ui/components peerDependencies），不要使用此处提到的构建版本。安装 Flux 和 @basmilius/vite-preset 时请使用 @latest dist-tag，不要猜测 caret 版本范围。
• 每个 Flux 软件包都需要一个 Vite 插件（flux()、fluxApplication()、fluxStatistics()）。缺少插件时，该软件包会解析到 dist，且 CSS 不会被导入，导致应用外壳／图表没有样式。
• 必须使用 FluxRoot。 将其挂载为应用包装器，否则 showAlert／showConfirm／showPrompt／showSnackbar、FluxOverlay 和 FluxTooltip 会抛出异常。

3. 命名规则（最常见的陷阱）

名称采用以 Flux 为前缀的 PascalCase。大多数名称只需将文档路径转换为 PascalCase（form/field → FluxFormField），但有几组名称不遵循此规则；猜错是最常见的错误。以下三种模式尤其需要留意：

• 变体移到前面： button/primary → FluxPrimaryButton，pane/clickable → FluxClickablePane。
• 省略一个路径段： layout/flex → FluxFlex，form/toggle → FluxToggle。
• 重新排序／添加后缀： form/slider/ranged → FluxFormRangeSlider，filter/async-option → FluxFilterOptionAsync。

对 button/*、form/*（控件）、layout/*、pane/* 和 filter/* 下的名称都要保持警惕并查阅文档。基础按钮是 FluxButton；分组包装器各有自己的名称（FluxButtonStack、FluxFormRadioGroup 等）。包含所有陷阱且已通过构建验证的完整列表见 references/component-index.md（请从这里开始）。

4. 选择组件（选择指南）

根据需求选择组件；在 references/component-index.md 中确认准确名称。

• 按钮 → FluxPrimaryButton / FluxSecondaryButton / FluxDestructiveButton、FluxSplitButton（操作 + 菜单）、FluxButtonStack（行）。 不要使用裸的 FluxButton。普通链接 → FluxLink。
• 表单 → 在 FluxForm 中将每个控件包裹在 FluxFormField 内。容易混淆的名称： 开关是 FluxToggle，步进器是 FluxQuantitySelector，范围滑块是 FluxFormRangeSlider， 日期输入框是 FluxFormDateInput。组合方式：references/forms.md。
• 对话框和反馈 → 通过代码调用 showConfirm / showPrompt / showAlert / showSnackbar；适用于丰富内容或可深度链接的场景：FluxOverlay / FluxSlideOver；内联 组件：FluxNotice / FluxBadge / FluxTooltip。references/dialogs-and-feedback.md。
• 布局、表格和导航 → FluxFlex / FluxGrid / FluxContainer、 FluxPane（卡片表面）、FluxSplitView；FluxDataTable / FluxTable、 FluxKanban、FluxTreeView、FluxCalendar；FluxMenu、FluxTabs、FluxStepper、 FluxCommandPalette、FluxSegmentedControl。references/components.md。
• 仪表板 / 多页面应用 → 使用 @flux-ui/application 外壳 + @flux-ui/statistics 来构建关键指标 / 图表，不要手动编写布局。 references/patterns.md §6、references/ecosystem.md。
• 排版 / 文本 → 使用 FluxText（Flux 字体比例：字号 / 字重 / 颜色、等宽数字、截断）， 不要使用原始 HTML + 自定义 CSS。
• 组合式函数 → useBreakpoints（响应式）、useFluxStore（全局存储）、 use*Injection（自定义控件）。references/conventions.md。

5. 组合与约定（关键规则）

可直接复制的骨架（应用外壳、CRUD 表单、数据表、仪表板、对话框）位于 references/patterns.md；跨组件的规则位于 references/conventions.md。 正确嵌套包装器比传递属性更重要。打开文件前请先了解以下内容：

• 表单： FluxForm › FluxPaneBody › FluxFormField（标签 / 提示 / 错误）› 控件；提交按钮为 FluxPrimaryButton is-submit。面板： FluxPane › FluxPaneHeader / FluxPaneBody / FluxPaneFooter。
• 分割按钮： 两个部分必须使用相同的变体（下拉箭头内部是 FluxSecondaryButton，因此 #button 插槽中也要放置一个 FluxSecondaryButton）。references/patterns.md §5。
• Overlay / slide-over 的 v-if： 将其放在面板内部，绝不要放在表面本身上 （@close 也要放在那里），否则组件会立即卸载并跳过离场过渡。references/dialogs-and-feedback.md。
• 图标使用已注册的 Font Awesome 名称字符串；还要注册组件文档页中列出的“必需图标”。 容易混淆的地方： FluxIcon / FluxBoxedIcon 通过 name 而非 icon 接收图标。
• gap / 间距 = 像素数值；颜色 = FluxColor 令牌 （gray | primary | danger | info | success | warning）；内置深色模式。
• 类型（FluxIconName、FluxColor、FluxTo 等）从 @flux-ui/types 导入，而非 @flux-ui/components（否则会出现类型错误）。
• 每个组件都必须导入，否则 Vue 会将未知标签按小写形式原样渲染（不会提示，也不会导致构建错误）。

以上内容的详细说明：references/conventions.md。

6. 需要准确的属性时

切勿假设某个属性存在：打开组件的文档页面（所有 URL 均列于 references/component-index.md），查看 Props / Emits / Slots 和准确的导入方式。

参考文件

• references/component-index.md - 每个组件和过渡效果的完整列表，已通过构建验证，包含文档 URL 和命名陷阱。从这里开始。
• references/conventions.md - 安装、Vite 预设、FluxRoot、Font Awesome 注册、路由/Nuxt、设计令牌、颜色、深色模式、类型、prop 与 slot 的区别，以及组合式函数 / 全局 API。
• references/patterns.md - 生产应用中的惯用端到端骨架：应用外壳、CRUD 表单、数据表格 + 筛选器、确认→操作→Snackbar 循环、窗格组合和仪表板。
• references/components.md - 如何选择和组合布局、表格及导航组件（选哪个，以及如何组合各部分）。
• references/forms.md - 表单组、Field 组合、控件和 CRUD 表单模式。
• references/dialogs-and-feedback.md - 覆盖层与编程调用的区别、show* 函数及其实际返回类型、通知和行内反馈。
• references/ecosystem.md - 同系列软件包 @flux-ui/application（应用外壳）和 @flux-ui/statistics（KPI/图表），以及它们的导出接口。

相关技能

• vue-component-anatomy - 介绍这些组件周边各个 .vue 文件的构建方式：区块顺序、宏顺序、prop 和 emit 类型。
• vue-build-feature - 将一个功能拆分到视图、组件、组合式函数和路由中；Flux 提供用于组合的组件。
• basmilius - 介绍通常用于 Flux UI 背后的 @basmilius/* 软件包（作者相同，作用域不同）：DTO 服务、存储、useDataTable。