Mantine 8.x 升级到 9.x 需要满足哪些前置条件和破坏性变更【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine如果你的项目还在使用 Mantine 8.x想要升级到大版本 9.x需要处理两类事情一是满足 9.x 对 React 及个别配套依赖的最低版本要求二是完成一组 API 上的破坏性变更props 改名、组件改名、hook 拆分、类型变更。仓库内可直接对照的资料是 8.x → 9.x 迁移指南 和 9.0.0 版本日志。本文以这两份文档为依据给出前置条件、依赖更新清单和逐项破坏性变更的改法。前置条件React 19.2 是硬性要求迁移指南的 Prerequisites 一节明确Mantine 9.x 要求 React 19.2 或更高版本。mantine/core等包的peerDependencies也印证了这一点packages/mantine/core/package.json 中声明react: ^19.2.0、react-dom: ^19.2.0。如果项目还在用旧版 React需要先升级 React 到 19.2再升级 Mantine。如果暂时无法升级 React文档给出的选项是继续使用 Mantine 8.x等 React 升级后再迁移到 9.x。此外有两个条件依赖取决于你用到哪些包来源为 9.0.0 版本日志 的 Peer dependencies requirements updates 一节使用的 Mantine 包额外依赖要求说明所有mantine/*包React 19.2见上mantine/tiptapTiptap 3迁移指南要求将tiptap/*包更新到最新 3.x 版本packages/mantine/tiptap/package.json 中 peer 依赖为tiptap/extension-link 3.3.0、tiptap/react 3.3.0。Tiptap 2 → 3 的改法见 Tiptap 3 迁移指南mantine/chartsRecharts 3版本日志说明无需迁移no migration required直接把recharts更新到最新 3.x 即可packages/mantine/charts/package.json 中 peer 依赖为recharts 3.2.1更新依赖迁移指南给出的操作步骤当前仓库的 9.x 版本为 9.6.0见根目录 package.json将所有mantine/*包更新到 9.x仓库当前版本为 9.6.0可按项目需要选择 9.x 内的具体版本若使用mantine/tiptap将所有tiptap/*包更新到最新 3.x 版本若使用mantine/charts将recharts更新到最新 3.x 版本。依赖升级完成后TypeScript 类型报错和运行时的行为差异就是下面这些破坏性变更的集中体现。组件与 props 破坏性变更Text / Anchor 的 color prop 被移除Text和Anchor组件不再接受colorprop改用c样式 propimport { Text } from mantine/core; // ❌ No longer works function Demo() { return Text colorredText/Text; } // ✅ Use the c style prop function Demo() { return Text credText/Text; }组件与 props 改名清单以下改名在迁移指南和 9.0.0 版本日志中均有记载可在代码库中按旧名搜索后逐一替换旧用法8.x新用法9.x说明TypographyStylesProviderTypography组件整体改名Typography 文档Collapse in{...}Collapse expanded{...}见下方代码示例Spoiler initialState{...}Spoiler defaultExpanded{...}与其他 Mantine 组件命名保持一致Grid gutterxlGrid gapxl新增rowGap/columnGap可分别控制行、列间距Popover/Tooltip的positionDependenciesprop直接删除该 prop位置现在会自动计算不再需要手动传入依赖项Collapse 改名示例import { Collapse } from mantine/core; // ❌ No longer works Collapse in{false}{/* ... */}/Collapse // ✅ Use the expanded prop Collapse expanded{false}{/* ... */}/CollapseGrid 的新增独立间距控制可选使用import { Grid } from mantine/core; // ✅ New: Separate row and column gaps Grid rowGapxl columnGapsm Grid.Col span{6}1/Grid.Col Grid.Col span{6}2/Grid.Col /GridGrid 的 overflowhidden 可以移除非强制9.x 的Grid不再用负边距实现列间距改用原生 CSSgap因此overflowhidden不再是防止内容溢出的必要手段可以从Grid上安全移除// ❌ overflowhidden is no longer needed Grid overflowhidden.../Grid // ✅ Remove overflowhidden Grid.../Grid这是一项清理而非必改项但保留它没有意义。Hook 破坏性变更use-fullscreen 拆分为两个 hookuseFullscreen被拆分为useFullscreenElement和useFullscreenDocument迁移指南说明拆分原因是修复旧实现中的 stale ref 问题。原来作用于document的用法改用useFullscreenDocument作用于自定义元素的用法改用useFullscreenElement。use-mouse 拆分为两个 hookuseMouse被拆分为useMouseref 场景和useMousePositiondocument 场景同样是为了修复 stale ref 问题。8.x 中const { x, y } useMouse()的 document 用法9.x 中应改用useMousePosition。use-mutation-observer 不再支持第三个 target 参数8.x 中把外部元素作为第三个参数传入的方式被移除改用新增的useMutationObserverTargetimport { useMutationObserverTarget } from mantine/hooks; useMutationObserverTarget( (mutations) console.log(mutations), { childList: true }, document.getElementById(external-element) );其他 hook 的类型变化mantine/hooks类型改名UseScrollSpyReturnType→UseScrollSpyReturnValue、StateHistory→UseStateHistoryValue、OS→UseOSReturnValue在代码库中直接替换类型名即可。useLocalStorage/useSessionStorage返回值类型修正不提供defaultValue时返回值类型现在是T | undefined8.x 错误地标注为T但运行时本来就可能为undefined。依赖旧类型的位置需要处理undefined或补上defaultValueimport { useLocalStorage } from mantine/hooks; // ✅ In 9.x, value is typed as string | undefined const [value, setValue] useLocalStorage({ key: my-key }); // ✅ Provide defaultValue to keep the previous non-undefined type const [value, setValue] useLocalStorage({ key: my-key, defaultValue: , });同样的变化也适用于readLocalStorageValue、useSessionStorage和readSessionStorageValue。useHeadroom返回对象而非布尔值现在返回{ pinned: boolean; scrollProgress: number }取pinned字段即可保持原来的判断逻辑import { useHeadroom } from mantine/hooks; // ❌ In 8.x, the return type is plain boolean const pinned useHeadroom({ fixedAt: 120 }); // ✅ In 9.x, the return type is an object containing pinned property const { pinned } useHeadroom({ fixedAt: 120 });Form 相关变更useForm 第二个泛型参数含义变化useForm的第二个泛型参数现在是转换后值的类型而不是转换函数类型。transformValues的用法不变但泛型标注要改成目标类型import { useForm } from mantine/form; interface FormValues { name: string; locationId: string; } interface TransformedValues { name: string; locationId: number; } function Demo() { const form useFormFormValues, TransformedValues({ mode: uncontrolled, initialValues: { name: , locationId: 2, }, transformValues: (values) ({ ...values, locationId: Number(values.locationId), }), }); }表单校验 resolverzodResolver 等不再导出9.x 的mantine/form内置了 Standard Schema 支持迁移指南原文中的链接文档站路径。zodResolver不再从mantine/form导出。如果 schema 库支持 Standard SchemaZod v4、Valibot、ArkType应改用内置的schemaResolverimport { z } from zod/v4; import { useForm, schemaResolver } from mantine/form; const schema z.object({ email: z.email({ error: Invalid email }), }); const form useForm({ initialValues: { email: }, validate: schemaResolver(schema, { sync: true }), });{ sync: true }用于同步 schema使form.validate()、form.validateField()、form.isValid()返回同步结果而不是 Promise9.0.0 版本日志对 Standard Schema 支持有同样的示例。默认行为变化如何保留 8.x 的外观与交互以下几项是默认值变化不影响编译但会改变视觉和交互。迁移指南为每项都给出了保留 8.x 行为的开关可以在迁移期间先保留旧行为之后再逐步接受新默认值。light 变体颜色改用实色值9.x 中light变体的 CSS 变量从不透明度的方式改为实色值。迁移期间需要保持 8.x 表现时在MantineProvider上使用v8CssVariablesResolverimport { Button, MantineProvider, v8CssVariablesResolver, } from mantine/core; function Demo() { return ( MantineProvider cssVariablesResolver{v8CssVariablesResolver} Button variantlight colorblue.6 Uses 8.x light variant colors /Button /MantineProvider ); }v8CssVariablesResolver在 packages/mantine/core/src/core/MantineProvider/MantineCssVariables/v8-css-variables-resolver.ts 中定义随mantine/core导出。默认圆角从 sm(4px) 变为 md(8px)8.x 的theme.defaultRadius是sm4px9.x 改为md8px。保留旧值import { createTheme, MantineProvider } from mantine/core; const theme createTheme({ defaultRadius: sm, }); function Demo() { return MantineProvider theme{theme}{/* Your app */}/MantineProvider; }Notifications 悬停暂停行为变化8.x 中悬停某条通知只暂停该通知的自动关闭计时器9.x 默认悬停任意可见通知会暂停所有可见通知的计时器。保留旧行为import { Notifications } from mantine/notifications; function Demo() { return Notifications pauseResetOnHovernotification /; }另外 9.0.0 版本日志还提到一处外观默认值变化medium字重从500变为600可用theme.fontWeights如fontWeights: { medium: 500 }恢复 8.x 值。验证与收尾迁移指南没有提供独立的校验命令它的检查方式是逐项的上面每个小节都给出了 ❌ No longer works / ✅ 的 8.x 与 9.x 对比示例。实际验证路径是编译与类型检查完成所有改名后跑一次 TypeScript 类型检查。Text/Anchor的color、Collapse的in、Grid的gutter、useLocalStorage未处理undefined等情况都会在类型层暴露出来。视觉核对重点检查使用了light变体的组件是否已决定接受实色新默认值还是通过v8CssVariablesResolver保持 8.x 表现以及默认圆角defaultRadius是否需要锁回sm。交互核对Notifications悬停暂停范围、Popover/Tooltip在依赖项变化时的位置更新positionDependencies移除后位置会自动重算。如果暂时无法把 React 升到 19.2迁移指南给出的明确选项是继续使用 Mantine 8.x等 React 升级后再执行本文的迁移步骤。【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考