Feishin 的 Mantine 组件封装约定统一 Wrapper 层的设计与实践【免费下载链接】feishinA modern self-hosted music player.项目地址: https://gitcode.com/gh_mirrors/fe/feishinFeishin一款现代化的自托管音乐播放器在渲染层全面使用 Mantine 构建界面但并非让业务代码直接依赖mantine/*而是在src/shared/components/与src/shared/hooks/之下维护一层统一 Wrapper包装层。本文以 docs/agents/mantine.md 为核心结合仓库源码深入讲解这套约定业务代码应如何导入组件、何时才允许打开上游 Mantine 文档、新增 Wrapper 的完整流程以及主题定制与 Mantine 的关系。读完本文你将掌握在 Feishin 代码库中正确使用 Mantine、调试 Wrapper 并新增受控组件/hook 的完整实战方案。一、为什么 Feishin 要包装 MantineWrapper 层的定位从架构上看Feishin 对 Mantine 采取的是**隔离 包装**策略业务代码features、layouts、store 等只允许从//shared/...导入禁止直接 importmantine/core等上游包mantine/*只允许出现在 Wrapper 模块内部以及少数共享的主题/类型工具中。这样做的收益非常明确版本可控升级 Mantine 大版本时只需在 Wrapper 层集中适配业务代码零改动风格统一Wrapper 内统一注入 Feishin 的 CSS Modules、主题变量var(--theme-*)与默认行为如 Button 默认sizesm、Modal 默认centered主题可替换Feishin 支持用户加载自定义桌面主题 JSONWrapper 层配合 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 给出的约定只有三步从//shared/components/...和//shared/hooks/...导入匹配现有调用方与 props 用法——Wrapper 本身就是 API以仓库内已有调用为准不臆造新写法不要抓取 Mantine 的 LLM 文档、MCP 或上游 skills除非命中何时打开上游文档一节的条件。mantine/*只属于 Wrapper 模块内部以及少数共享主题/类型工具。这条规则与 docs/agents/frontend.md 中的导入约定表完全一致用途路径共享 UI / hooks / 主题//shared/...→src/shared/...Features / layouts / stores//renderer/...→src/renderer/...i18n//i18n/...或按邻近文件的写法使用react-i18next/i18nextfrontend.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 ModulesclassNames{{ inner: styles.inner, label: styles.label, root: styles.root, ... }}并使用clsx组合条件类名如uppercase开关扩展了业务侧需要的 propstooltip自动包裹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、radiusmd、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/...再导出。触发上述场景后的操作顺序确认 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优先使用 Mantine MCP若已配置search_docs、get_item_doc、get_item_props三个工具否则访问mantine.dev/llms.txt再顺着链接仅打开对应组件的单页.md不要把llms-full.txt整个引入仓库禁止 vendoring。也就是说默认场景下Wrapper 即 API只有触及 Wrapper 本身时才回到上游源码对照避免业务代码与上游 API 直接耦合。四、新增 Wrapper 与 Skill 分支仅限新包装组件/hook只有当需要脚手架化一个全新的Wrapper 时才从 mantinedev/skills 仓库安装对应 Skill。文档给出的对应关系如下新 Wrapper 类型对应 Skillmantine/form/ 校验 / form contextmantine-form基于Combobox的自定义 Selectmantine-comboboxFactory Styles API 组件mantine-custom-components例如要为业务方提供自定义下拉选择如多选、异步选项、分组选项就属于基于 Combobox 的自定义 Select应安装并使用mantine-comboboxskill 来脚手架 Wrapper然后放到src/shared/components/下并遵循既有component-name.module.csscomponent-name.tsx的布局kebab-case 命名CSS 类名 kebab-case、经 Vite 映射为styles.camelCase。注意这些 Skill 只服务于新增包装这一种场景为既有 Wrapper 修 Bug 时不应引入。五、Wrapper 之外的例外命令式 API 与主题桥接mantine/modals是明确例外docs/agents/frontend.md 指出mantine/modalsopenModal、openContextModal、closeModal等是业务侧常用的命令式 APIfeatures 中允许直接使用只需匹配邻近调用方的写法。这一例外在 modal.tsx 中也得到印证——该文件本身就从mantine/modals转发openModal/closeAllModals供业务代码通过 Wrapper 路径间接使用。主题对象Mantine 主题如何与自定义主题共存Feishin 的主题体系分层清晰见 frontend.md 的表格层来源类型 / 形状src/shared/themes/app-theme-types.ts内置主题src/shared/themes/*注册表 app-theme.ts运行时 CSS 变量以--theme-*/--theme-colors-*注入见 use-app-themeMantine 主题对象src/renderer/themes/mantine-theme.tsx桥接到 Mantine 变量src/shared/styles/global.cssmantine-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落地时可按以下清单自检导入路径优先//shared/components/xxx/xxx与//shared/hooks/xxx深导入不要 importmantine/core布局原语用共享的Box、Flex、Stack、Group、Grid组装界面而不是写一次性 layout div只有通用设计系统原语才放进 shared否则留在 feature-local 或 feature-shared样式CSS Modules 与组件文件同目录同名词干类名 kebab-caseMantine Wrapper 通过 Styles API 的classNames传入模块类颜色与间距优先用var(--theme-*)/var(--theme-colors-*)避免裸 hex 与--mantine-*保证自定义主题可用明暗分叉用 PostCSSmixin light-root/dark-root允许lighten/darken/alpha命令式 UItoast 用//shared/components/toast/toast的toast.success|error|info|warn({ message, title? })modal 用mantine/modals的openModal等或共享Modal/ModalButton/ provider 模式受控显隐优先用//shared/hooks/use-disclosure调 Bug / 加 Wrapper确认 package.json 中 Mantine v9使用 Mantine MCP 或按需打开单页文档不要 vendoring 完整llms-full.txt新增包装类型按上表匹配mantine-form/mantine-combobox/mantine-custom-componentsskill 脚手架涉及主题对象形状变更才去读 docs/CUSTOM_THEMES.md。遵循这套约定业务代码与上游 Mantine 保持解耦升级、换肤、全局样式注入都收敛在src/shared/一层这正是 Feishin 能够在保持界面高度定制化数十套内置主题 用户自定义 JSON的同时将 Mantine 使用面稳定控制在 Wrapper 之内的原因。参考文档与源码docs/agents/mantine.md本文核心约定来源docs/agents/frontend.md渲染层整体约定docs/CUSTOM_THEMES.md自定义主题 JSON 与mantineOverridepackage.jsonMantine v9 依赖清单electron.vite.config.ts//shared别名解析src/shared/components/button/button.tsxWrapper 组件示例src/shared/components/modal/modal.tsxModal 包装与mantine/modals例外src/shared/components/toast/toast.tsxtoast 包装示例src/shared/hooks/use-disclosure.tsWrapper hook 示例src/renderer/themes/mantine-theme.tsxMantine 主题对象构建src/shared/themes/app-theme-types.ts主题类型/形状src/shared/styles/global.cssMantine 变量桥接【免费下载链接】feishinA modern self-hosted music player.项目地址: https://gitcode.com/gh_mirrors/fe/feishin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Feishin 的 Mantine 组件封装约定：统一 Wrapper 层的设计与实践
Feishin 的 Mantine 组件封装约定统一 Wrapper 层的设计与实践【免费下载链接】feishinA modern self-hosted music player.项目地址: https://gitcode.com/gh_mirrors/fe/feishinFeishin一款现代化的自托管音乐播放器在渲染层全面使用 Mantine 构建界面但并非让业务代码直接依赖mantine/*而是在src/shared/components/与src/shared/hooks/之下维护一层统一 Wrapper包装层。本文以 docs/agents/mantine.md 为核心结合仓库源码深入讲解这套约定业务代码应如何导入组件、何时才允许打开上游 Mantine 文档、新增 Wrapper 的完整流程以及主题定制与 Mantine 的关系。读完本文你将掌握在 Feishin 代码库中正确使用 Mantine、调试 Wrapper 并新增受控组件/hook 的完整实战方案。一、为什么 Feishin 要包装 MantineWrapper 层的定位从架构上看Feishin 对 Mantine 采取的是**隔离 包装**策略业务代码features、layouts、store 等只允许从//shared/...导入禁止直接 importmantine/core等上游包mantine/*只允许出现在 Wrapper 模块内部以及少数共享的主题/类型工具中。这样做的收益非常明确版本可控升级 Mantine 大版本时只需在 Wrapper 层集中适配业务代码零改动风格统一Wrapper 内统一注入 Feishin 的 CSS Modules、主题变量var(--theme-*)与默认行为如 Button 默认sizesm、Modal 默认centered主题可替换Feishin 支持用户加载自定义桌面主题 JSONWrapper 层配合 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 给出的约定只有三步从//shared/components/...和//shared/hooks/...导入匹配现有调用方与 props 用法——Wrapper 本身就是 API以仓库内已有调用为准不臆造新写法不要抓取 Mantine 的 LLM 文档、MCP 或上游 skills除非命中何时打开上游文档一节的条件。mantine/*只属于 Wrapper 模块内部以及少数共享主题/类型工具。这条规则与 docs/agents/frontend.md 中的导入约定表完全一致用途路径共享 UI / hooks / 主题//shared/...→src/shared/...Features / layouts / stores//renderer/...→src/renderer/...i18n//i18n/...或按邻近文件的写法使用react-i18next/i18nextfrontend.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 ModulesclassNames{{ inner: styles.inner, label: styles.label, root: styles.root, ... }}并使用clsx组合条件类名如uppercase开关扩展了业务侧需要的 propstooltip自动包裹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、radiusmd、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/...再导出。触发上述场景后的操作顺序确认 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优先使用 Mantine MCP若已配置search_docs、get_item_doc、get_item_props三个工具否则访问mantine.dev/llms.txt再顺着链接仅打开对应组件的单页.md不要把llms-full.txt整个引入仓库禁止 vendoring。也就是说默认场景下Wrapper 即 API只有触及 Wrapper 本身时才回到上游源码对照避免业务代码与上游 API 直接耦合。四、新增 Wrapper 与 Skill 分支仅限新包装组件/hook只有当需要脚手架化一个全新的Wrapper 时才从 mantinedev/skills 仓库安装对应 Skill。文档给出的对应关系如下新 Wrapper 类型对应 Skillmantine/form/ 校验 / form contextmantine-form基于Combobox的自定义 Selectmantine-comboboxFactory Styles API 组件mantine-custom-components例如要为业务方提供自定义下拉选择如多选、异步选项、分组选项就属于基于 Combobox 的自定义 Select应安装并使用mantine-comboboxskill 来脚手架 Wrapper然后放到src/shared/components/下并遵循既有component-name.module.csscomponent-name.tsx的布局kebab-case 命名CSS 类名 kebab-case、经 Vite 映射为styles.camelCase。注意这些 Skill 只服务于新增包装这一种场景为既有 Wrapper 修 Bug 时不应引入。五、Wrapper 之外的例外命令式 API 与主题桥接mantine/modals是明确例外docs/agents/frontend.md 指出mantine/modalsopenModal、openContextModal、closeModal等是业务侧常用的命令式 APIfeatures 中允许直接使用只需匹配邻近调用方的写法。这一例外在 modal.tsx 中也得到印证——该文件本身就从mantine/modals转发openModal/closeAllModals供业务代码通过 Wrapper 路径间接使用。主题对象Mantine 主题如何与自定义主题共存Feishin 的主题体系分层清晰见 frontend.md 的表格层来源类型 / 形状src/shared/themes/app-theme-types.ts内置主题src/shared/themes/*注册表 app-theme.ts运行时 CSS 变量以--theme-*/--theme-colors-*注入见 use-app-themeMantine 主题对象src/renderer/themes/mantine-theme.tsx桥接到 Mantine 变量src/shared/styles/global.cssmantine-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落地时可按以下清单自检导入路径优先//shared/components/xxx/xxx与//shared/hooks/xxx深导入不要 importmantine/core布局原语用共享的Box、Flex、Stack、Group、Grid组装界面而不是写一次性 layout div只有通用设计系统原语才放进 shared否则留在 feature-local 或 feature-shared样式CSS Modules 与组件文件同目录同名词干类名 kebab-caseMantine Wrapper 通过 Styles API 的classNames传入模块类颜色与间距优先用var(--theme-*)/var(--theme-colors-*)避免裸 hex 与--mantine-*保证自定义主题可用明暗分叉用 PostCSSmixin light-root/dark-root允许lighten/darken/alpha命令式 UItoast 用//shared/components/toast/toast的toast.success|error|info|warn({ message, title? })modal 用mantine/modals的openModal等或共享Modal/ModalButton/ provider 模式受控显隐优先用//shared/hooks/use-disclosure调 Bug / 加 Wrapper确认 package.json 中 Mantine v9使用 Mantine MCP 或按需打开单页文档不要 vendoring 完整llms-full.txt新增包装类型按上表匹配mantine-form/mantine-combobox/mantine-custom-componentsskill 脚手架涉及主题对象形状变更才去读 docs/CUSTOM_THEMES.md。遵循这套约定业务代码与上游 Mantine 保持解耦升级、换肤、全局样式注入都收敛在src/shared/一层这正是 Feishin 能够在保持界面高度定制化数十套内置主题 用户自定义 JSON的同时将 Mantine 使用面稳定控制在 Wrapper 之内的原因。参考文档与源码docs/agents/mantine.md本文核心约定来源docs/agents/frontend.md渲染层整体约定docs/CUSTOM_THEMES.md自定义主题 JSON 与mantineOverridepackage.jsonMantine v9 依赖清单electron.vite.config.ts//shared别名解析src/shared/components/button/button.tsxWrapper 组件示例src/shared/components/modal/modal.tsxModal 包装与mantine/modals例外src/shared/components/toast/toast.tsxtoast 包装示例src/shared/hooks/use-disclosure.tsWrapper hook 示例src/renderer/themes/mantine-theme.tsxMantine 主题对象构建src/shared/themes/app-theme-types.ts主题类型/形状src/shared/styles/global.cssMantine 变量桥接【免费下载链接】feishinA modern self-hosted music player.项目地址: https://gitcode.com/gh_mirrors/fe/feishin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考