Cette compétence fournit des motifs pour Tamagui v1.x qui vont au-delà des fondamentaux. Elle se concentre sur la Configuration v4, l'optimisation du compilateur, les composants composés et les erreurs courantes.
Chargement Obligatoire du Contexte
Lorsque vous travaillez avec ces composants, lisez le fichier de motif correspondant AVANT d'écrire du code :
| Type de Composant | Lecture Obligatoire | Compétences Transversales |
|---|---|---|
| Dialog, Sheet, superpositions modales | @DIALOG_PATTERNS.md | |
| Form, Input, Label, validation | @FORM_PATTERNS.md | typescript-best-practices (zod) |
| Animations, transitions | @ANIMATION_PATTERNS.md | |
| Popover, Tooltip, Select | @OVERLAY_PATTERNS.md | |
| Optimisation du compilateur | @COMPILER_PATTERNS.md | |
| Jetons de design, thématisation | @DESIGN_SYSTEM.md |
Démarrage Rapide avec la Configuration v4
Utilisez @tamagui/config/v4 pour une configuration simplifiée :
// tamagui.config.ts
import { defaultConfig } from '@tamagui/config/v4'
import { createTamagui } from 'tamagui'
export const config = createTamagui(defaultConfig)
type CustomConfig = typeof config
declare module 'tamagui' {
interface TamaguiCustomConfig extends CustomConfig {}
}
Réglage recommandé pour les nouveaux projets (aligne flexBasis sur React Native) :
export const config = createTamagui({
...defaultConfig,
settings: {
...defaultConfig.settings,
styleCompat: 'react-native',
},
})
Motif createThemes
Pour des thèmes personnalisés, utilisez createThemes avec palette/accent/childrenThemes :
import { createThemes, defaultComponentThemes } from '@tamagui/config/v4'
const generatedThemes = createThemes({
componentThemes: defaultComponentThemes,
base: {
palette: {
dark: ['#050505', '#151515', /* ...12 couleurs */ '#fff'],
light: ['#fff', '#f8f8f8', /* ...12 couleurs */ '#000'],
},
extra: {
light: { ...Colors.blue, shadowColor: 'rgba(0,0,0,0.04)' },
dark: { ...Colors.blueDark, shadowColor: 'rgba(0,0,0,0.2)' },
},
},
accent: {
palette: { dark: lightPalette, light: darkPalette }, // inversé
},
childrenThemes: {
blue: { palette: { dark: Object.values(Colors.blueDark), light: Object.values(Colors.blue) } },
red: { /* ... */ },
green: { /* ... */ },
},
})
Syntaxe des Jetons et des Thèmes
Règles pour le Préfixe $
- Props : Utilisez le préfixe
$pour les références aux jetons :<Text color="$color" fontSize="$4" /> - Clés de thème : Accédez sans
$dans les définitions de thème :{ color: palette[11] } - Accès aux jetons dans les variantes : Utilisez le motif
tokens.size[name]
Opérateurs de Déploiement pour les Variantes
Des opérateurs spéciaux de déploiement mappent des catégories de jetons aux valeurs des variantes :
const Button = styled(View, {
variants: {
size: {
// Mappe les jetons de taille : $1, $2, $true, etc.
'...size': (size, { tokens }) => ({
height: tokens.size[size] ?? size,
borderRadius: tokens.radius[size] ?? size,
gap: tokens.space[size]?.val * 0.2,
}),
},
textSize: {
// Mappe les jetons de taille de police
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
Important : Utilisez as const sur l'objet des variantes jusqu'à ce que TypeScript supporte les génériques const inférés.
Composants Composés avec createStyledContext
Pour des API composées telles que <Button><Button.Text>Cliquez</Button.Text></Button> :
import {
SizeTokens,
View,
Text,
createStyledContext,
styled,
withStaticProperties,
} from '@tamagui/core'
// 1. Créez un contexte avec des types de variantes partagés
export const ButtonContext = createStyledContext<{ size: SizeTokens }>({
size: '$medium',
})
// 2. Créez le cadre avec contexte
export const ButtonFrame = styled(View, {
name: 'Button',
context: ButtonContext,
variants: {
size: {
'...size': (name, { tokens }) => ({
height: tokens.size[name],
borderRadius: tokens.radius[name],
gap: tokens.space[name].val * 0.2,
}),
},
} as const,
defaultVariants: {
size: '$medium',
},
})
// 3. Créez le texte avec le même contexte (les variantes se synchronisent automatiquement)
export const ButtonText = styled(Text, {
name: 'ButtonText',
context: ButtonContext,
variants: {
size: {
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
// 4. Composez avec withStaticProperties
export const Button = withStaticProperties(ButtonFrame, {
Props: ButtonContext.Provider,
Text: ButtonText,
})
Utilisation :
<Button size="$large">
<Button.Text>Cliquez ici</Button.Text>
</Button>
// Ou remplacez les valeurs par défaut depuis le haut :
<Button.Props size="$small">
<Button><Button.Text>Petit</Button.Text></Button>
</Button.Props>
Remarque : Le motif context ne fonctionne pas avec l'aplatissement du compilateur. Utilisez-le pour les composants de haut niveau (Button, Card), pas pour les primitives (Stack, Text).
styleable() pour les Composants d'Encapsulation
Lorsque vous encapsulez un composant stylisé dans un composant fonctionnel, utilisez .styleable() pour préserver l'héritage des variantes :
const StyledText = styled(Text)
// SANS styleable - Héritage de variante CASSÉ
const BrokenWrapper = (props) => <StyledText {...props} />
// AVEC styleable - CORRECT
const CorrectWrapper = StyledText.styleable((props, ref) => (
<StyledText ref={ref} {...props} />
))
// Maintenant cela fonctionne :
const StyledCorrectWrapper = styled(CorrectWrapper, {
variants: {
bold: { true: { fontWeight: 'bold' } },
},
})
Ajout de Props Supplémentaires
Passez un argument de type générique pour les props supplémentaires :
type ExtraProps = { icon?: React.ReactNode }
const IconText = StyledText.styleable<ExtraProps>((props, ref) => {
const { icon, ...rest } = props
return (
<XStack>
{icon}
<StyledText ref={ref} {...rest} />
</XStack>
)
})
Propriété accept pour les Composants Personnalisés
Activez la résolution du jeton/du thème sur des props non standard :
// Pour SVG fill/stroke qui devrait accepter les couleurs du thème
const StyledSVG = styled(SVG, {}, {
accept: { fill: 'color', stroke: 'color' } as const,
})
// Utilisation : <StyledSVG fill="$blue10" />
// Pour les objets de style (comme contentContainerStyle de ScrollView)
const MyScrollView = styled(ScrollView, {}, {
accept: { contentContainerStyle: 'style' } as const,
})
// Utilisation : <MyScrollView contentContainerStyle={{ padding: '$4' }} />
Important : Utilisez as const sur l'objet accept.
L'Ordre des Props a de l'Importance
Dans styled(), l'ordre des props détermine la priorité de remplacement :
// backgroundColor peut être remplacé par des props
const Overridable = (props) => (
<View backgroundColor="$red10" {...props} width={200} />
)
// width NE peut PAS être remplacé (vient après le déploiement)
// L'ordre des variantes compte aussi :
<Component scale={3} huge /> // scale = 3 (scale vient en premier)
<Component huge scale={3} /> // scale = 2 (huge remplace)
Anti-Patrons
Les Styles Dynamiques Cassent l'Optimisation
// MAUVAIS - casse l'optimisation du compilateur
<View style={{ width: someVariable * 2 }} />
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />
// BON - utilisez des variantes
const Box = styled(View, {
variants: {
dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
},
})
<Box dark={isDark} />
Fonctions en Ligne
// MAUVAIS - nouvelle fonction à chaque rendu
<View onPress={() => handlePress(id)} />
// BON - référence stable
const handlePressCallback = useCallback(() => handlePress(id), [id])
<View onPress={handlePressCallback} />
Mauvais Chemins d'Import
// Ce sont des paquets différents avec des contenus différents :
import { View } from 'tamagui' // Kit UI complet
import { View } from '@tamagui/core' // Core uniquement (plus petit)
import { Button } from '@tamagui/button' // Composant individuel
// Choisissez une approche et soyez cohérent
Mélanger RN StyleSheet avec Tamagui
// MAUVAIS - les valeurs StyleSheet ne résolvent pas les jetons
const styles = StyleSheet.create({ box: { padding: 20 } })
<View style={styles.box} backgroundColor="$blue10" />
// BON - tout Tamagui
<View padding="$4" backgroundColor="$blue10" />
Ramification Platform.OS pour Dialog/Sheet
// MAUVAIS - ramification manuelle de la plateforme
if (Platform.OS === 'web') {
return <Dialog>...</Dialog>
}
return <Sheet>...</Sheet>
// BON - utilisez Adapt (voir @DIALOG_PATTERNS.md)
<Dialog>
<Dialog.Portal>...</Dialog.Portal>
<Adapt when="sm" platform="touch">
<Sheet><Adapt.Contents /></Sheet>
</Adapt>
</Dialog>
Récupération de la Documentation Actuelle
Pour les détails les plus récents de l'API, récupérez directement les docs en markdown :
# Docs du core
curl -sL "https://tamagui.dev/docs/core/configuration.md"
curl -sL "https://tamagui.dev/docs/core/styled.md"
curl -sL "https://tamagui.dev/docs/core/variants.md"
curl -sL "https://tamagui.dev/docs/core/animations.md"
# Docs des composants
curl -sL "https://tamagui.dev/ui/sheet.md"
curl -sL "https://tamagui.dev/ui/dialog.md"
curl -sL "https://tamagui.dev/ui/select.md"
# Index complet des docs
curl -sL "https://tamagui.dev/llms.txt"
Pour les pages HTML, utilisez la compétence web-fetch avec des sélecteurs appropriés.
Référence Rapide
Raccourcis de la Configuration v4 (Alignés sur Tailwind)
| Raccourci | Propriété |
|---|---|
bg | backgroundColor |
p | padding |
m | margin |
w | width |
h | height |
br | borderRadius |
Points de Rupture des Requêtes Média
| Jeton | Par Défaut | Par Défaut Serveur |
|---|---|---|
$xs | 660px | true |
$sm | 800px | false |
$md | 1020px | false |
$lg | 1280px | false |
$xl | 1420px | false |
Pilotes d'Animation
| Pilote | Plateforme | Cas d'Utilisation |
|---|---|---|
css | Web | Par défaut, meilleures performances |
react-native-reanimated | Natif | Requis pour les animations natives |
Fichiers de Motifs Supplémentaires
- @DIALOG_PATTERNS.md - Dialog, Sheet, Adapt, accessibilité
- @FORM_PATTERNS.md - Form, Input, Label, validation avec zod
- @ANIMATION_PATTERNS.md - Pilotes d'animation, enterStyle/exitStyle
- @OVERLAY_PATTERNS.md - Popover, Tooltip, Select
- @COMPILER_PATTERNS.md - Détails de l'optimisation du compilateur
- @DESIGN_SYSTEM.md - Jetons de design et thématisation