企业官网建设流程全解析

Feishin 的 Mantine 组件封装约定：统一 Wrapper 层的设计与实践

【免费下载链接】feishinA modern self-hosted music player.项目地址: https://gitcode.com/gh_mirrors/fe/feishin

Feishin（一款现代化的自托管音乐播放器）在渲染层全面使用 Mantine 构建界面，但并非让业务代码直接依赖@mantine/*，而是在src/shared/components/与src/shared/hooks/之下维护一层统一 Wrapper（包装层）。本文以 docs/agents/mantine.md 为核心，结合仓库源码深入讲解这套约定：业务代码应如何导入组件、何时才允许打开上游 Mantine 文档、新增 Wrapper 的完整流程，以及主题定制与 Mantine 的关系。读完本文，你将掌握在 Feishin 代码库中正确使用 Mantine、调试 Wrapper 并新增受控组件/hook 的完整实战方案。

一、为什么 Feishin 要包装 Mantine：Wrapper 层的定位

从架构上看，Feishin 对 Mantine 采取的是**"隔离 + 包装"**策略：

• 业务代码（features、layouts、store 等）只允许从/@/shared/...导入，禁止直接 import@mantine/core等上游包；
• @mantine/*只允许出现在 Wrapper 模块内部，以及少数共享的主题/类型工具中。

这样做的收益非常明确：

1. 版本可控：升级 Mantine 大版本时，只需在 Wrapper 层集中适配，业务代码零改动；
2. 风格统一：Wrapper 内统一注入 Feishin 的 CSS Modules、主题变量（var(--theme-*)）与默认行为（如 Button 默认size="sm"、Modal 默认centered）；
3. 主题可替换：Feishin 支持用户加载自定义桌面主题 JSON，Wrapper 层配合 docs/CUSTOM_THEMES.md 的主题对象形状，确保自定义主题能持续生效。

从 electron.vite.config.ts 可以看到别名解析的依据：渲染进程（renderer）的resolve.alias将/@/shared指向src/shared，同时配置了/@/i18n、/@/renderer、/@/remote等别名。这就是为什么代码里写/@/shared/components/button/button会被正确解析到 src/shared/components/button/button.tsx。

注意：Web 构建配置（web.vite.config.ts）与 remote SPA 构建配置（remote.vite.config.ts）虽然面向不同入口，但同样遵循"业务代码走/@/shared"的分层原则。

二、默认工作流（绝大多数 UI 开发场景）

对于绝大多数 UI 工作，docs/agents/mantine.md 给出的约定只有三步：

1. 从/@/shared/components/...和/@/shared/hooks/...导入；
2. 匹配现有调用方与 props 用法——Wrapper 本身就是 API，以仓库内已有调用为准，不臆造新写法；
3. 不要抓取 Mantine 的 LLM 文档、MCP 或上游 skills，除非命中"何时打开上游文档"一节的条件。

@mantine/*只属于 Wrapper 模块内部（以及少数共享主题/类型工具）。这条规则与 docs/agents/frontend.md 中的导入约定表完全一致：

frontend.md还强调：只做深导入，不建 barrel（组件桶），例如/@/shared/components/button/button直接定位到具体组件文件，避免index.ts聚合导出带来的树摇与依赖问题。

Wrapper 的真实面貌：源码级剖析

以 button.tsx 为例，可以看到 Wrapper 的典型结构：

• 从@mantine/core导入Button as MantineButton、ButtonVariant、ButtonProps as MantineButtonProps，再通过createPolymorphicComponent（来自 src/shared/utils/create-polymorphic-component.ts）导出多态组件；
• 通过 Mantine 的Styles API注入 CSS Modules：classNames={{ inner: styles.inner, label: styles.label, root: styles.root, ... }}，并使用clsx组合条件类名（如uppercase开关）；
• 扩展了业务侧需要的 props：tooltip（自动包裹Tooltip）、uppercase，以及额外的variant值state-error/state-info/state-success/state-warning；
• 设置默认值：size = 'sm'、variant = 'default'；
• 额外导出TimeoutButton（带倒计时取消逻辑，借助 use-timeout）等业务复合件。

Hook 侧同样如此，例如 use-disclosure.ts 就是一行转发：

import { useDisclosure as useMantineDisclosure } from '@mantine/hooks'; export const useDisclosure = useMantineDisclosure;

而 modal.tsx 展示了"命令式 API 留在@mantine/modals、声明式组件走 Wrapper"的边界：openModal/closeAllModals直接转发自@mantine/modals，同时导出受控的Modal（强制centered、radius="md"、300ms fade 过渡、半透明模糊遮罩，且以ScrollArea作为滚动容器）、ConfirmModal、BaseContextModal与ModalsProvider。

toast.tsx 则把@mantine/notifications包装成项目内惯用的toast.success|error|info|warn({ message, title? })对象，并为每种类型映射默认标题（Success/Warning/Error/Info）与对应 CSS 类。

从源码结构可以推断：src/shared/components/下共有数十个包装组件（accordion、autocomplete、badge、box、button、checkbox、color-input、date-picker、dialog、drawer、dropdown-menu、fieldset、flex、grid、group、hover-card、icon、image、modal、multi-select、number-input、pagination、paper、popover、portal、progress、rating、scroll-area、select、slider、spinner、stack、switch、table、tabs、text-input、tooltip 等），src/shared/hooks/下对应包装了 use-click-outside、use-debounced-*、use-disclosure、use-hotkeys、use-local-storage、use-media-query、use-timeout 等常用 hooks。新增 UI 时先在这些目录里找现成 Wrapper，找不到再考虑新增。

三、何时打开上游 Mantine 文档

并非任何时候都禁止查阅官方资料。docs/agents/mantine.md 明确列出两种必须查阅上游文档的场景：

• 调试某个 Wrapper：行为/Bug 位于src/shared/components/*或src/shared/hooks/*（或相邻的共享 Mantine 适配层）；
• 新增一个被包装的组件或 hook：即引入一个此前不存在的/@/shared/...再导出。

触发上述场景后的操作顺序：

1. 确认 Mantine v9：查看 package.json，当前依赖为@mantine/core、@mantine/dates、@mantine/form、@mantine/hooks、@mantine/modals、@mantine/notifications、@mantine/colors-generator均为^9.3.0，构建侧还包含postcss-preset-mantine（^1.18.0）与postcss-simple-vars；
2. 优先使用 Mantine MCP（若已配置）：search_docs、get_item_doc、get_item_props三个工具；否则访问mantine.dev/llms.txt，再顺着链接仅打开对应组件的单页.md；
3. 不要把llms-full.txt整个引入仓库（禁止 vendoring）。

也就是说：默认场景下"Wrapper 即 API"，只有触及 Wrapper 本身时才回到上游源码对照，避免业务代码与上游 API 直接耦合。

四、新增 Wrapper 与 Skill 分支（仅限新包装组件/hook）

只有当需要"脚手架化"一个全新的Wrapper 时，才从 mantinedev/skills 仓库安装对应 Skill。文档给出的对应关系如下：

例如：要为业务方提供自定义下拉选择（如多选、异步选项、分组选项），就属于"基于 Combobox 的自定义 Select"，应安装并使用mantine-comboboxskill 来脚手架 Wrapper，然后放到src/shared/components/下并遵循既有component-name.module.css+component-name.tsx的布局（kebab-case 命名，CSS 类名 kebab-case、经 Vite 映射为styles.camelCase）。

注意：这些 Skill 只服务于新增包装这一种场景，为既有 Wrapper 修 Bug 时不应引入。

五、Wrapper 之外的例外：命令式 API 与主题桥接

@mantine/modals是明确例外

docs/agents/frontend.md 指出：@mantine/modals（openModal、openContextModal、closeModal等）是业务侧常用的命令式 API，features 中允许直接使用，只需匹配邻近调用方的写法。这一例外在 modal.tsx 中也得到印证——该文件本身就从@mantine/modals转发openModal/closeAllModals，供业务代码通过 Wrapper 路径间接使用。

主题对象：Mantine 主题如何与自定义主题共存

Feishin 的主题体系分层清晰（见 frontend.md 的表格）：

mantine-theme.tsx 展示了二者如何合并：createMantineTheme(theme: AppThemeConfiguration)用lodash/merge将基础 Mantine 主题（自定义 breakpoints、fontSizes、headings、radius、shadows、spacing、primaryColor: 'primary'、autoContrast: true、focusRing: 'never'、默认 Loader 为 Spinner 等）与来自theme.colors的primary/dark/black/white以及theme.mantineOverride合并，再经createTheme输出。也就是说：用户加载的自定义桌面主题 JSON 中，mantineOverride字段可以深度覆盖 Mantine 主题对象的任意部分。

docs/agents/mantine.md 最后一条"Repo theme notes"特别强调：用户可加载的桌面主题 JSON 与mantineOverride的完整格式见 docs/CUSTOM_THEMES.md，只有当你要修改该行为或主题对象形状时才需要打开这份文档——日常业务开发无需关心。

六、实用建议：在 Feishin 中写 UI 的检查清单

综合 docs/agents/mantine.md 与 docs/agents/frontend.md，落地时可按以下清单自检：

1. 导入路径：优先/@/shared/components/xxx/xxx与/@/shared/hooks/xxx深导入；不要 import@mantine/core；
2. 布局原语：用共享的Box、Flex、Stack、Group、Grid组装界面，而不是写一次性 layout div；只有通用设计系统原语才放进 shared，否则留在 feature-local 或 feature-shared；
3. 样式：CSS Modules 与组件文件同目录同名词干；类名 kebab-case；Mantine Wrapper 通过 Styles API 的classNames传入模块类；颜色与间距优先用var(--theme-*)/var(--theme-colors-*)，避免裸 hex 与--mantine-*，保证自定义主题可用；明暗分叉用 PostCSS@mixin light-root/dark-root，允许lighten/darken/alpha；
4. 命令式 UI：toast 用/@/shared/components/toast/toast的toast.success|error|info|warn({ message, title? })；modal 用@mantine/modals的openModal等，或共享Modal/ModalButton/ provider 模式，受控显隐优先用/@/shared/hooks/use-disclosure；
5. 调 Bug / 加 Wrapper：确认 package.json 中 Mantine v9，使用 Mantine MCP 或按需打开单页文档，不要 vendoring 完整llms-full.txt；
6. 新增包装类型：按上表匹配mantine-form/mantine-combobox/mantine-custom-componentsskill 脚手架；
7. 涉及主题对象形状变更：才去读 docs/CUSTOM_THEMES.md。

遵循这套约定，业务代码与上游 Mantine 保持解耦：升级、换肤、全局样式注入都收敛在src/shared/一层，这正是 Feishin 能够在保持界面高度定制化（数十套内置主题 + 用户自定义 JSON）的同时，将 Mantine 使用面稳定控制在 Wrapper 之内的原因。

参考文档与源码

• docs/agents/mantine.md（本文核心约定来源）
• docs/agents/frontend.md（渲染层整体约定）
• docs/CUSTOM_THEMES.md（自定义主题 JSON 与mantineOverride）
• package.json（Mantine v9 依赖清单）
• electron.vite.config.ts（/@/shared别名解析）
• src/shared/components/button/button.tsx（Wrapper 组件示例）
• src/shared/components/modal/modal.tsx（Modal 包装与@mantine/modals例外）
• src/shared/components/toast/toast.tsx（toast 包装示例）
• src/shared/hooks/use-disclosure.ts（Wrapper hook 示例）
• src/renderer/themes/mantine-theme.tsx（Mantine 主题对象构建）
• src/shared/themes/app-theme-types.ts（主题类型/形状）
• src/shared/styles/global.css（Mantine 变量桥接）

【免费下载链接】feishinA modern self-hosted music player.项目地址: https://gitcode.com/gh_mirrors/fe/feishin