tamagui

Tamagui Skill

适用于 Web 和原生平台的通用 React UI 框架。在 v3 中，条件是样式值中的扁平子句，令牌和主题都是不带前缀的名称，并且已移除 hoverStyle 等嵌套条件属性。

1. 优先配置项目

编写 Tamagui 代码前，先生成或读取项目提示词：

npx tamagui generate-prompt

此操作会生成 tamagui-prompt.md，其中包含项目确切的令牌名称、主题键、媒体断点、简写和组件。在现有应用中，始终先检查并使用项目本地的组件封装，然后再从原始包导入。

2. 扁平值语法

所有条件样式值都遵循以下语法：

value  := base? clause*
clause := modifier(:modifier)*:payload

• 修饰符从左到右串联：dark:hover:navy 在 dark 和 hover 条件都匹配时生效。
• 值部分延伸至下一个顶层子句或字符串末尾。
• 值部分不能为空。使用 none、transparent、initial 或 unset 清除属性。
• 不要编写带子句的原始 transform 字符串；请使用原子变换属性（scale、rotate、x、y）。

支持的修饰符

• 交互：hover:、press:、focus:、focus-visible:、focus-within:、disabled:
• 媒体：已配置的键，例如 sm:（最小宽度）、max-sm:（最大宽度）、md:、max-md:
• 主题：dark:、light: 和已配置的主题名称
• 平台：web:、native:、ios:、android:
• 组：group-hover:、group-hover/name:、group-press/name:
• 容器：@sm:、@sm/name:（测量最近的查询容器）
• 存在状态：enter:、exit:（需要 transition=）

规则

1. 不加 $ 前缀：令牌和主题名称不带前缀：bg="background"、p="4"，而不是 bg="$background"。
2. 主题名称使用 kebab-case：内置主题键使用 kebab-case：background-hover、background-press、border-color、border-color-hover、placeholder-color、shadow-color。
3. 数字单位为 px：带引号的数字字符串 p="4" 会解析为已配置的间距令牌。原始数值字面量 p={4} 在 Web 上表示 4px，在原生平台上表示 4 点。
4. 特异性优先级阶梯：多个子句匹配时，根据特异性而非编写顺序决定生效项：
   • 平台级别（ios: > native: > 无前缀）
   • 条件数量（条件越多，优先级越高）
   • 类别级别：media（1）< container（65）< theme（129）< group（161）< state（225）
   • 只有在特异性完全相同时，才按编写顺序决定。
   • 一个链最多支持五个不同的非平台条件。

3. 样式值语法

Tamagui 支持字符串和对象两种语法。项目可以通过 settings.styleValueSyntax 配置强制使用其中一种。

字符串形式

import { View } from 'tamagui'

export function Demo() {
  return (
    <View
      bg="background hover:background-hover dark:blue-500"
      p="4 sm:6 max-sm:2"
      w="100% md:50%"
      opacity="web:0.9"
      scale="1 enter:0.9 exit:0.9"
      transition="quick"
    />
  )
}

对象形式

import { View } from 'tamagui'

export function Demo() {
  return (
    <View
      bg={{ default: 'background', hover: 'background-hover', dark: 'blue-500' }}
      p={{ default: '4', sm: '6', 'max-sm': '2' }}
      w={{ default: '100%', md: '50%' }}
      opacity={{ web: 0.9 }}
      scale={{ default: 1, enter: 0.9, exit: 0.9 }}
      transition="quick"
    />
  )
}

4. 简写与完整属性名

查看 tamagui-prompt.md 中的 onlyAllowShorthands。在默认的 v6 配置下，该选项为 true，这意味着完整属性名会从类型中移除，并导致类型错误。始终使用简写：

• p、px、py、pt、pb、pl、pr：内边距
• m、mx、my、mt、mb、ml、mr：外边距
• w、h、minW、maxW、minH、maxH：尺寸
• bg：背景
• color：文本颜色（v6 中不缩写）
• rounded：边框圆角
• items：对齐项目
• justify：两端对齐内容

5. 控件尺寸

使用 v6 配置时，控件（Button、Input、Select 等）接受命名尺寸：xs、sm、md、lg、xl。默认值为 md。

import { Button, YStack } from 'tamagui'

export function Buttons() {
  return (
    <YStack gap="2">
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </YStack>
  )
}

控件尺寸请使用命名配方。size="4" 等旧版令牌键仍受支持，但采用旧的基于高度的尺寸模型。Spinner 有自己的 small 和 large 尺寸。

6. 组与容器

在父级上将 group 和 container 声明为属性，然后在子级中指定目标：

import { Text, View } from 'tamagui'

export function CardGroup() {
  return (
    <View group="card" container="card">
      <Text color="color group-hover/card:color-focus @sm/card:color">Card title</Text>
    </View>
  )
}

7. 动画与存在状态

v3 的动画属性为 transition（不是 animation）。对于进入和退出过渡，请指定 enter: 和 exit: 子句，并使用显式的 key 将卸载组件包裹在 AnimatePresence 中：

import { AnimatePresence, View } from 'tamagui'

export function Fade({ visible }: { visible: boolean }) {
  return (
    <AnimatePresence>
      {visible && (
        <View
          key="fade-box"
          opacity="1 enter:0 exit:0"
          scale="1 enter:0.9 exit:0.9"
          transition="quick"
        />
      )}
    </AnimatePresence>
  )
}

8. 已移除的 V2 API 及其替代方案

V2 API	V3 替代方案
hoverStyle={{ ... }}	bg="background hover:background-hover" 或 bg={{ hover: '...' }}
pressStyle={{ ... }}	press: 子句：scale="1 press:0.95"
focusStyle={{ ... }}	focus: 子句
enterStyle={{ ... }} / exitStyle={{ ... }}	配合 transition="preset" 使用 enter: / exit: 子句
animation="fast"	transition="fast"
$sm={{ ... }}	样式属性中的 sm: 子句：p="2 sm:4"
Sheet.Frame	Sheet.Container 和 Sheet.Background
Component.styleable(fn)	createStyledHOC(Component, fn)
useProps, useStyle	splitStyleProps, getExpandedShorthand
Select.Item index={i}	已移除 index 属性；请使用 <Select.Item value="val">

9. 要导入的包

• tamagui：带皮肤的样式化组件（Button、Input、Dialog、Sheet 等）
• tamagui/unstyled（@tamagui/ui）：仅包含结构样式的无样式基元
• @tamagui/core：核心样式运行时（View、Text、styled）
• html.*：支持 Tamagui 扁平值的 DOM 元素（html.div、html.span）

10. 验证

使用以下命令验证样式和语法：

npx tamagui check --strict

settings.allowedStyleValues 控制单令牌值的类型验证。条件负载和修饰符还需要运行 tamagui check --strict；该命令会在全新项目中加载项目配置。

如需了解详细 API，请阅读配置、组件和动画。