tamagui

Tamagui スキル

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 文字列は記述しないでください。アトミックな 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. テーマ名はケバブケース：組み込みのテーマキーはケバブケースを使用します。background-hover、background-press、border-color、border-color-hover、placeholder-color、shadow-color などです。
3. 数値の単位は px：引用符で囲んだ数値文字列 p="4" は、設定された space トークンに解決されます。数値リテラル p={4} は、Web では 4px、ネイティブでは 4 ポイントとして扱われます。
4. 詳細度による優先順位：複数の節が一致する場合、優先されるものは記述順ではなく詳細度で決まります。
   • プラットフォームのランク（ios: > native: > 指定なし）
   • 条件の数（多いほうが優先）
   • カテゴリーのランク：メディア（1）< コンテナ（65）< テーマ（129）< グループ（161）< 状態（225）
   • 記述順は、詳細度が完全に同じ場合のみ優先順位を決めます。
   • 1 つのチェーンで指定できる、プラットフォーム以外の異なる条件は最大 5 つです。

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 を props として指定し、子からそれらを参照します。

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 のアニメーション用 prop は 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 と代替 API

V2 API	V3 の代替 API
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 については、設定、コンポーネント、アニメーションを参照してください。