尧图网站建设 
如何将 Tamagui 项目从 v1 升级到 v2【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamagui如果你的 Tamagui 项目还在 v1 上需要升级到 v2这篇指南按官方升级文档给出完整的操作路径。v2 对齐了现代 Web 标准、改进了性能并简化了 API官方对迁移量的评估是“中等”——主要工作是移除已废弃的 API、重命名 props 和更新配置。开始前项目需要满足 Tamagui 2 的硬性前提React 19React Native 0.81需启用 New Architecture原生端TypeScript 5官方要求先把这三个依赖升到位再进行下面的迁移步骤。1. 升级依赖版本把所有tamagui/*和tamagui包的版本升到^2.0.0升级后用 CLI 检查依赖一致性npx tamagui checknpx tamagui check会扫描项目并报告版本不一致的包这在 monorepo 中尤其重要因为 core 包出现多份副本会导致 context/provider 失效。有两个 v1 包在 v2 中已被移除需要替换tamagui/animations-moti→ 改用tamagui/animations-reanimated同一套 APItamagui/image-next→ 直接使用tamagui包导出的Imagemonorepo 建议再显式添加 resolutions避免 core 包重复安装resolutions: { tamagui/core: ^2.0.0, tamagui/web: ^2.0.0, tamagui: ^2.0.0 }2. 配置迁移config/v4 到 config/v5注意v4 到 v5 的配置迁移并非强制可以先只升 Tamagui 2、之后再做 v5 配置迁移。但如果迁移注意 v5 改动了部分默认样式行为媒体查询命名、部分主题和颜色值也有差异。更新导入并单独选择动画驱动v5 起动画不再随 config 捆绑需要单独导入并选一个驱动tamagui/config/v5-css—— CSS transitions体积最小仅 Webtamagui/config/v5-rn—— React Native Animated APItamagui/config/v5-reanimated—— Reanimated原生端性能最佳tamagui/config/v5-motion—— MotionWeb Animations API实验性// before import { defaultConfig } from tamagui/config/v4 // after import { defaultConfig } from tamagui/config/v5 import { animations } from tamagui/config/v5-css // 动画现在单独导入把animations传给createTamaguiimport { defaultConfig } from tamagui/config/v5 import { animations } from tamagui/config/v5-css import { createTamagui } from tamagui export const config createTamagui({ ...defaultConfig, animations, }) export type Conf typeof config declare module tamagui { interface TamaguiCustomConfig extends Conf {} }根级设置移入 settings 对象v1 中createTamagui的根级设置在 v2 中统一移入settings对象// before (v1) createTamagui({ defaultFont: body, disableRootThemeClass: true, }) // after (v2) createTamagui({ ...defaultConfig, settings: { ...defaultConfig.settings, // your overrides }, })同时有几个设置被移除或调整maxDarkLightNesting—— 完全移除cssStyleSeparator—— 完全移除themeClassNameOnRoot—— 改由addThemeClassName处理disableRootThemeClass—— 现在属于settings注意 flex 和 position 默认值变化v5 改了两个影响布局的默认值flexBasis从auto变为0React Native 标准position从relative变为static浏览器默认如果你的布局依赖旧行为在settings中恢复settings: { ...defaultConfig.settings, styleCompat: legacy, // 恢复 flexBasis: auto defaultPosition: relative, // 恢复 position: relative }否则需要给包含绝对定位子元素的容器显式加positionrelative在需要的地方补flexBasisauto。媒体查询改名断点值现在与 Tailwind CSS 对齐640、768、1024、1280、1536部分查询名要改$2xl→$xxl$2xs→$xxs$max2Xl→$max-xxl$maxXl→$max-xl$maxLg→$max-lg$maxMd→$max-md$maxSm→$max-smmax 查询从 camelCase 改为 kebab-case。v5 还新增了高度类查询$height-sm、$height-md等和$pointerTouch查询可按需使用。颜色与主题颜色值更新为 Radix Colors v3个别色值与 v1 略有差异旧色值可从tamagui/colors/legacy获取。v5 新增orange、pink、purple、teal、gray、neutral颜色主题。主题构建从tamagui/theme-builder的createThemes简化为tamagui/themes/v5的createV5Themeimport { createV5Theme, defaultChildrenThemes } from tamagui/themes/v5 const themes createV5Theme({ childrenThemes: { ...defaultChildrenThemes, // add custom color themes cyan: { light: cyan, dark: cyanDark }, }, })组件主题在 v5 中默认关闭改用配置里的defaultPropscreateTamagui({ ...defaultConfig, defaultProps: { Button: { theme: accent }, }, })官方建议在 v5 配置就绪后运行npx tamagui generate-prompt并把输出提交到仓库方便 AI 辅助工具理解你的配置、加速后续迁移。3. 组件 props 重命名这部分是最常见的查找替换官方给出了一组替换模式建议逐处审查后再改旧写法新写法animationtransitionAnimationPropTransitionPropAnimationKeysTransitionKeystagrenderthemeInversethemeaccentTheme inverseTheme nameaccentStack/StackPropsView/ViewPropsonHoverInonPointerEnteronHoverOutonPointerLeave$2xl/$2xs$xxl/$xxsmaxMD/maxLG/maxSM/maxXL/max2Xlmax-md/max-lg/max-sm/max-xl/max-xxl几个典型的 before/after// before View animationbouncy / View tagnav / YStack space$4 spaceDirectionboth Text ellipseLong text.../Text // after View transitionbouncy / View rendernav / YStack gap$4 Text numberOfLines{1}Long text.../Text补充两点taga的场景建议改用Anchor组件space/spaceDirection统一改为gap。4. 阴影迁移到 boxShadowReact Native 风格的阴影 props 替换为 CSSboxShadow格式为x y blur color// before View shadowColor$shadow3 shadowRadius{20} shadowOffset{{ height: 10, width: 0 }} / // after View boxShadow0 10px 20px $shadow3 /多阴影用逗号分隔spread 和 inset 也受支持。5. 无障碍 props 改为 ARIA所有 React Native 无障碍 props 换成 Web 标准 ARIA 等价物常用映射accessibilityLabel→aria-labelaccessibilityRole→roleaccessibilityState{{ disabled }}→aria-disabledaccessibilityState{{ selected }}→aria-selectedaccessibilityElementsHidden→aria-hiddenaccessibilityViewIsModal→aria-modalaccessible→tabIndex{0}focusable→tabIndexnativeID→id完整映射含accessibilityHint、accessibilityValue、accessibilityLiveRegion等见 升级文档。6. 组件 API 变化Input改为以 Web 标准 HTML 属性为主旧 RN props 仍可用但已废弃// before Input keyboardTypeemail-address secureTextEntry returnKeyTypesend onChangeText{(text) setText(text)} editable{false} / // after Input inputModeemail typepassword enterKeyHintsend autoCompleteemail onChange{(e) setText(e.target?.value ?? e.nativeEvent?.text ?? )} readOnly /Image优先使用 Web 标准srcRN 的source迁移期仍可用但已废弃// before Image source{{ uri: https://example.com/photo.jpg, width: 200, height: 200 }} resizeModecover / // after Image srchttps://example.com/photo.jpg width{200} height{200} objectFitcover /其他组件的关键变化Button文本样式 props 从直接 API 移除通过子组件控制文字样式默认typebuttonuseButtonhook 废弃ListItem内部间距 propsspaceFlex、scaleSpace移除用ListItem.Text、ListItem.SubtitleTabsactivationMode默认从automatic改为manualTabs.Trigger废弃改用Tabs.TabGroup子元素必须包在Group.Item里space、separator等 props 移除需要分隔线时手动加Separator /Popover.Sheet.*被独立Sheet取代// after Adapt whenmax-md platformtouch Sheet modal dismissOnSnapToBottom Sheet.Frame p$4 Adapt.Contents / /Sheet.Frame Sheet.Overlay transitionquick / /Sheet /AdaptToast从ToastProvider包裹结构改为Toaster兄弟节点结构import { toast, Toaster } from tamagui/toast/v2 function App() { return ( Toaster positionbottom-right / Button onPress{() toast(Hello!)}Show Toast/Button / ) }Toaster需挂在TamaguiProvider内部通常放在导航或根布局旁边。7. 已移除的 API移除项替代方案Spacer /core 中从tamagui/spacer导入composeEventHandlers手动组合(val) { a(val); b?.(val) }useTheme(props)使用Theme组件ThemeableStack使用Viewbackgroundedpropbg$backgroundselectablepropselecttext行内animatePresenceprop用AnimatePresence组件包裹scrollbarWidthprop用 CSSisWindowDefined用tamagui/constants的isBrowseruseThemefromtamagui/next-theme改名为useThemeSettingtamagui/react-native-use-responder-events用 pointer eventsonPointerDown等8. 原生端 setup 导入v2 中原生功能需要在 app 入口、任何 Tamagui 导入之前显式导入 setup 模块。官方说明这些大多是新增的可选功能只有你在 v1 用过原生 gradient 或 toast 时才需要处理// portals (Sheet, Dialog, Popover, Select, Toast) import tamagui/native/setup-teleport // LinearGradient import tamagui/native/setup-expo-linear-gradient // Toast (burnt) import tamagui/native/setup-burnt // Menu (zeego) import tamagui/native/setup-zeego // for smoother Sheet on native: import tamagui/native/setup-gesture-handler使用 setup 模块前对应的原生依赖如react-native-teleport、zeego、burnt、react-native-gesture-handler需已安装monorepo 中应安装在父应用或 workspace 根而不是叶子包。如果使用 Expo Router这些导入必须先于expo-router/entry执行。创建自定义入口文件项目根目录// index.js (at project root) import tamagui/native/setup-zeego // add other setup imports here as needed import expo-router/entry并把package.json更新为{ main: index.js }9. 构建配置Vite项目使用tamagui/vite-plugin的插件与别名并在项目根创建tamagui.build.ts// vite.config import { tamaguiAliases, tamaguiPlugin } from tamagui/vite-plugin export default { plugins: [tamaguiPlugin()], resolve: { alias: [ ...tamaguiAliases({ rnwLite: true, // use lightweight react-native-web svg: true, }), ], }, }// tamagui.build.ts import type { TamaguiBuildOptions } from tamagui export default { components: [tamagui], config: ./src/tamagui.config.ts, outputCSS: ./src/tamagui.generated.css, } satisfies TamaguiBuildOptionsMetroExpo / React Native无需特殊配置标准 Expo Metro 配置即可直接工作。Next.jsTurbopack需要resolveExtensions和一个react-native-safe-area-contextshim// next.config.js module.exports { turbopack: { resolveAlias: { react-native: react-native-web, react-native-svg: tamagui/react-native-svg, react-native-safe-area-context: ./shims/react-native-safe-area-context.js, }, resolveExtensions: [ .web.tsx, .web.ts, .web.js, .web.jsx, .tsx, .ts, .js, .jsx, .json, ], }, }CSS官方建议生成到tamagui.generated.css并替换旧的tamagui.css导入生成命令npx tamagui generate-css --output ./src/tamagui.generated.css验证与收尾迁移完成后按文档做三项核对运行npx tamagui check确认各tamagui/*依赖版本一致monorepo 尤其要跑。更新快照测试阴影颜色在 v2 中改用color-mix()生成旧快照会不匹配。对照官方 Migration Checklist 逐项勾掉重点检查容易漏改的declare module tamagui类型增强、Group.Item包裹、Tabs的activationMode默认值变化、原生 setup 导入顺序。两点边界说明一是 v5 配置迁移可选官方建议“先升 Tamagui 2之后再迁 v5 配置”以降低一次改动面二是 v2 原生端依赖 React Native 0.81 的新样式能力boxShadow、filter等Web 端无版本限制。完成以上步骤并通过npx tamagui check后项目即完成 v1 到 v2 的升级。【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamagui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何将 Tamagui 项目从 v1 升级到 v2？
如何将 Tamagui 项目从 v1 升级到 v2【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamagui如果你的 Tamagui 项目还在 v1 上需要升级到 v2这篇指南按官方升级文档给出完整的操作路径。v2 对齐了现代 Web 标准、改进了性能并简化了 API官方对迁移量的评估是“中等”——主要工作是移除已废弃的 API、重命名 props 和更新配置。开始前项目需要满足 Tamagui 2 的硬性前提React 19React Native 0.81需启用 New Architecture原生端TypeScript 5官方要求先把这三个依赖升到位再进行下面的迁移步骤。1. 升级依赖版本把所有tamagui/*和tamagui包的版本升到^2.0.0升级后用 CLI 检查依赖一致性npx tamagui checknpx tamagui check会扫描项目并报告版本不一致的包这在 monorepo 中尤其重要因为 core 包出现多份副本会导致 context/provider 失效。有两个 v1 包在 v2 中已被移除需要替换tamagui/animations-moti→ 改用tamagui/animations-reanimated同一套 APItamagui/image-next→ 直接使用tamagui包导出的Imagemonorepo 建议再显式添加 resolutions避免 core 包重复安装resolutions: { tamagui/core: ^2.0.0, tamagui/web: ^2.0.0, tamagui: ^2.0.0 }2. 配置迁移config/v4 到 config/v5注意v4 到 v5 的配置迁移并非强制可以先只升 Tamagui 2、之后再做 v5 配置迁移。但如果迁移注意 v5 改动了部分默认样式行为媒体查询命名、部分主题和颜色值也有差异。更新导入并单独选择动画驱动v5 起动画不再随 config 捆绑需要单独导入并选一个驱动tamagui/config/v5-css—— CSS transitions体积最小仅 Webtamagui/config/v5-rn—— React Native Animated APItamagui/config/v5-reanimated—— Reanimated原生端性能最佳tamagui/config/v5-motion—— MotionWeb Animations API实验性// before import { defaultConfig } from tamagui/config/v4 // after import { defaultConfig } from tamagui/config/v5 import { animations } from tamagui/config/v5-css // 动画现在单独导入把animations传给createTamaguiimport { defaultConfig } from tamagui/config/v5 import { animations } from tamagui/config/v5-css import { createTamagui } from tamagui export const config createTamagui({ ...defaultConfig, animations, }) export type Conf typeof config declare module tamagui { interface TamaguiCustomConfig extends Conf {} }根级设置移入 settings 对象v1 中createTamagui的根级设置在 v2 中统一移入settings对象// before (v1) createTamagui({ defaultFont: body, disableRootThemeClass: true, }) // after (v2) createTamagui({ ...defaultConfig, settings: { ...defaultConfig.settings, // your overrides }, })同时有几个设置被移除或调整maxDarkLightNesting—— 完全移除cssStyleSeparator—— 完全移除themeClassNameOnRoot—— 改由addThemeClassName处理disableRootThemeClass—— 现在属于settings注意 flex 和 position 默认值变化v5 改了两个影响布局的默认值flexBasis从auto变为0React Native 标准position从relative变为static浏览器默认如果你的布局依赖旧行为在settings中恢复settings: { ...defaultConfig.settings, styleCompat: legacy, // 恢复 flexBasis: auto defaultPosition: relative, // 恢复 position: relative }否则需要给包含绝对定位子元素的容器显式加positionrelative在需要的地方补flexBasisauto。媒体查询改名断点值现在与 Tailwind CSS 对齐640、768、1024、1280、1536部分查询名要改$2xl→$xxl$2xs→$xxs$max2Xl→$max-xxl$maxXl→$max-xl$maxLg→$max-lg$maxMd→$max-md$maxSm→$max-smmax 查询从 camelCase 改为 kebab-case。v5 还新增了高度类查询$height-sm、$height-md等和$pointerTouch查询可按需使用。颜色与主题颜色值更新为 Radix Colors v3个别色值与 v1 略有差异旧色值可从tamagui/colors/legacy获取。v5 新增orange、pink、purple、teal、gray、neutral颜色主题。主题构建从tamagui/theme-builder的createThemes简化为tamagui/themes/v5的createV5Themeimport { createV5Theme, defaultChildrenThemes } from tamagui/themes/v5 const themes createV5Theme({ childrenThemes: { ...defaultChildrenThemes, // add custom color themes cyan: { light: cyan, dark: cyanDark }, }, })组件主题在 v5 中默认关闭改用配置里的defaultPropscreateTamagui({ ...defaultConfig, defaultProps: { Button: { theme: accent }, }, })官方建议在 v5 配置就绪后运行npx tamagui generate-prompt并把输出提交到仓库方便 AI 辅助工具理解你的配置、加速后续迁移。3. 组件 props 重命名这部分是最常见的查找替换官方给出了一组替换模式建议逐处审查后再改旧写法新写法animationtransitionAnimationPropTransitionPropAnimationKeysTransitionKeystagrenderthemeInversethemeaccentTheme inverseTheme nameaccentStack/StackPropsView/ViewPropsonHoverInonPointerEnteronHoverOutonPointerLeave$2xl/$2xs$xxl/$xxsmaxMD/maxLG/maxSM/maxXL/max2Xlmax-md/max-lg/max-sm/max-xl/max-xxl几个典型的 before/after// before View animationbouncy / View tagnav / YStack space$4 spaceDirectionboth Text ellipseLong text.../Text // after View transitionbouncy / View rendernav / YStack gap$4 Text numberOfLines{1}Long text.../Text补充两点taga的场景建议改用Anchor组件space/spaceDirection统一改为gap。4. 阴影迁移到 boxShadowReact Native 风格的阴影 props 替换为 CSSboxShadow格式为x y blur color// before View shadowColor$shadow3 shadowRadius{20} shadowOffset{{ height: 10, width: 0 }} / // after View boxShadow0 10px 20px $shadow3 /多阴影用逗号分隔spread 和 inset 也受支持。5. 无障碍 props 改为 ARIA所有 React Native 无障碍 props 换成 Web 标准 ARIA 等价物常用映射accessibilityLabel→aria-labelaccessibilityRole→roleaccessibilityState{{ disabled }}→aria-disabledaccessibilityState{{ selected }}→aria-selectedaccessibilityElementsHidden→aria-hiddenaccessibilityViewIsModal→aria-modalaccessible→tabIndex{0}focusable→tabIndexnativeID→id完整映射含accessibilityHint、accessibilityValue、accessibilityLiveRegion等见 升级文档。6. 组件 API 变化Input改为以 Web 标准 HTML 属性为主旧 RN props 仍可用但已废弃// before Input keyboardTypeemail-address secureTextEntry returnKeyTypesend onChangeText{(text) setText(text)} editable{false} / // after Input inputModeemail typepassword enterKeyHintsend autoCompleteemail onChange{(e) setText(e.target?.value ?? e.nativeEvent?.text ?? )} readOnly /Image优先使用 Web 标准srcRN 的source迁移期仍可用但已废弃// before Image source{{ uri: https://example.com/photo.jpg, width: 200, height: 200 }} resizeModecover / // after Image srchttps://example.com/photo.jpg width{200} height{200} objectFitcover /其他组件的关键变化Button文本样式 props 从直接 API 移除通过子组件控制文字样式默认typebuttonuseButtonhook 废弃ListItem内部间距 propsspaceFlex、scaleSpace移除用ListItem.Text、ListItem.SubtitleTabsactivationMode默认从automatic改为manualTabs.Trigger废弃改用Tabs.TabGroup子元素必须包在Group.Item里space、separator等 props 移除需要分隔线时手动加Separator /Popover.Sheet.*被独立Sheet取代// after Adapt whenmax-md platformtouch Sheet modal dismissOnSnapToBottom Sheet.Frame p$4 Adapt.Contents / /Sheet.Frame Sheet.Overlay transitionquick / /Sheet /AdaptToast从ToastProvider包裹结构改为Toaster兄弟节点结构import { toast, Toaster } from tamagui/toast/v2 function App() { return ( Toaster positionbottom-right / Button onPress{() toast(Hello!)}Show Toast/Button / ) }Toaster需挂在TamaguiProvider内部通常放在导航或根布局旁边。7. 已移除的 API移除项替代方案Spacer /core 中从tamagui/spacer导入composeEventHandlers手动组合(val) { a(val); b?.(val) }useTheme(props)使用Theme组件ThemeableStack使用Viewbackgroundedpropbg$backgroundselectablepropselecttext行内animatePresenceprop用AnimatePresence组件包裹scrollbarWidthprop用 CSSisWindowDefined用tamagui/constants的isBrowseruseThemefromtamagui/next-theme改名为useThemeSettingtamagui/react-native-use-responder-events用 pointer eventsonPointerDown等8. 原生端 setup 导入v2 中原生功能需要在 app 入口、任何 Tamagui 导入之前显式导入 setup 模块。官方说明这些大多是新增的可选功能只有你在 v1 用过原生 gradient 或 toast 时才需要处理// portals (Sheet, Dialog, Popover, Select, Toast) import tamagui/native/setup-teleport // LinearGradient import tamagui/native/setup-expo-linear-gradient // Toast (burnt) import tamagui/native/setup-burnt // Menu (zeego) import tamagui/native/setup-zeego // for smoother Sheet on native: import tamagui/native/setup-gesture-handler使用 setup 模块前对应的原生依赖如react-native-teleport、zeego、burnt、react-native-gesture-handler需已安装monorepo 中应安装在父应用或 workspace 根而不是叶子包。如果使用 Expo Router这些导入必须先于expo-router/entry执行。创建自定义入口文件项目根目录// index.js (at project root) import tamagui/native/setup-zeego // add other setup imports here as needed import expo-router/entry并把package.json更新为{ main: index.js }9. 构建配置Vite项目使用tamagui/vite-plugin的插件与别名并在项目根创建tamagui.build.ts// vite.config import { tamaguiAliases, tamaguiPlugin } from tamagui/vite-plugin export default { plugins: [tamaguiPlugin()], resolve: { alias: [ ...tamaguiAliases({ rnwLite: true, // use lightweight react-native-web svg: true, }), ], }, }// tamagui.build.ts import type { TamaguiBuildOptions } from tamagui export default { components: [tamagui], config: ./src/tamagui.config.ts, outputCSS: ./src/tamagui.generated.css, } satisfies TamaguiBuildOptionsMetroExpo / React Native无需特殊配置标准 Expo Metro 配置即可直接工作。Next.jsTurbopack需要resolveExtensions和一个react-native-safe-area-contextshim// next.config.js module.exports { turbopack: { resolveAlias: { react-native: react-native-web, react-native-svg: tamagui/react-native-svg, react-native-safe-area-context: ./shims/react-native-safe-area-context.js, }, resolveExtensions: [ .web.tsx, .web.ts, .web.js, .web.jsx, .tsx, .ts, .js, .jsx, .json, ], }, }CSS官方建议生成到tamagui.generated.css并替换旧的tamagui.css导入生成命令npx tamagui generate-css --output ./src/tamagui.generated.css验证与收尾迁移完成后按文档做三项核对运行npx tamagui check确认各tamagui/*依赖版本一致monorepo 尤其要跑。更新快照测试阴影颜色在 v2 中改用color-mix()生成旧快照会不匹配。对照官方 Migration Checklist 逐项勾掉重点检查容易漏改的declare module tamagui类型增强、Group.Item包裹、Tabs的activationMode默认值变化、原生 setup 导入顺序。两点边界说明一是 v5 配置迁移可选官方建议“先升 Tamagui 2之后再迁 v5 配置”以降低一次改动面二是 v2 原生端依赖 React Native 0.81 的新样式能力boxShadow、filter等Web 端无版本限制。完成以上步骤并通过npx tamagui check后项目即完成 v1 到 v2 的升级。【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamagui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考