Dieses Skill bietet Muster für Tamagui v1.x, die über die Grundlagen hinausgehen. Es konzentriert sich auf Config v4, Compiler-Optimierung, zusammengesetzte Komponenten und häufige Fehler.
Pflichtkontext-Ladung
Wenn Sie mit diesen Komponenten arbeiten, lesen Sie die entsprechende Musterdatei, BEVOR Sie Code schreiben:
| Komponententyp | Erforderliche Lektüre | Übergreifende Skills |
|---|---|---|
| Dialog, Sheet, modale Overlays | @DIALOG_PATTERNS.md | |
| Form, Input, Label, Validierung | @FORM_PATTERNS.md | typescript-best-practices (zod) |
| Animationen, Übergänge | @ANIMATION_PATTERNS.md | |
| Popover, Tooltip, Select | @OVERLAY_PATTERNS.md | |
| Compiler-Optimierung | @COMPILER_PATTERNS.md | |
| Design-Tokens, Theming | @DESIGN_SYSTEM.md |
Config v4 Schnellstart
Verwenden Sie @tamagui/config/v4 für eine vereinfachte Einrichtung:
// 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 {}
}
Empfohlene Einstellung für neue Projekte (gleicht flexBasis an React Native an):
export const config = createTamagui({
...defaultConfig,
settings: {
...defaultConfig.settings,
styleCompat: 'react-native',
},
})
createThemes-Muster
Für benutzerdefinierte Themes verwenden Sie createThemes mit palette/accent/childrenThemes:
import { createThemes, defaultComponentThemes } from '@tamagui/config/v4'
const generatedThemes = createThemes({
componentThemes: defaultComponentThemes,
base: {
palette: {
dark: ['#050505', '#151515', /* ...12 Farben */ '#fff'],
light: ['#fff', '#f8f8f8', /* ...12 Farben */ '#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 }, // invertiert
},
childrenThemes: {
blue: { palette: { dark: Object.values(Colors.blueDark), light: Object.values(Colors.blue) } },
red: { /* ... */ },
green: { /* ... */ },
},
})
Token- und Theme-Syntax
$ Präfix-Regeln
- Props: Verwenden Sie das
$-Präfix für Token-Referenzen:<Text color="$color" fontSize="$4" /> - Theme-Schlüssel: Zugriff ohne
$in Theme-Definitionen:{ color: palette[11] } - Token-Zugriff in Variants: Verwenden Sie das Muster
tokens.size[name]
Variant-Spread-Operatoren
Spezielle Spread-Operatoren ordnen Token-Kategorien Variant-Werten zu:
const Button = styled(View, {
variants: {
size: {
// Ordnet Größen-Token zu: $1, $2, $true, usw.
'...size': (size, { tokens }) => ({
height: tokens.size[size] ?? size,
borderRadius: tokens.radius[size] ?? size,
gap: tokens.space[size]?.val * 0.2,
}),
},
textSize: {
// Ordnet fontSize-Token zu
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
Wichtig: Verwenden Sie as const für das Variants-Objekt, bis TypeScript inferierte const Generics unterstützt.
Zusammengesetzte Komponenten mit createStyledContext
Für zusammengesetzte APIs wie <Button><Button.Text>Click</Button.Text></Button>:
import {
SizeTokens,
View,
Text,
createStyledContext,
styled,
withStaticProperties,
} from '@tamagui/core'
// 1. Kontext mit gemeinsamen Variant-Typen erstellen
export const ButtonContext = createStyledContext<{ size: SizeTokens }>({
size: '$medium',
})
// 2. Frame mit Kontext erstellen
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. Text mit gleichem Kontext erstellen (Variants synchronisieren automatisch)
export const ButtonText = styled(Text, {
name: 'ButtonText',
context: ButtonContext,
variants: {
size: {
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
// 4. Mit withStaticProperties zusammensetzen
export const Button = withStaticProperties(ButtonFrame, {
Props: ButtonContext.Provider,
Text: ButtonText,
})
Verwendung:
<Button size="$large">
<Button.Text>Click me</Button.Text>
</Button>
// Oder Standardwerte von oben überschreiben:
<Button.Props size="$small">
<Button><Button.Text>Small</Button.Text></Button>
</Button.Props>
Hinweis: Das context-Muster funktioniert nicht mit Compiler-Flattening. Für übergeordnete Komponenten (Button, Card) verwenden, nicht für Primitive (Stack, Text).
styleable() für Wrapper-Komponenten
Wenn Sie eine gestylte Komponente in eine funktionale Komponente verpacken, verwenden Sie .styleable(), um die Vererbung von Variants zu erhalten:
const StyledText = styled(Text)
// OHNE styleable - UNTERBROCHENE Variant-Vererbung
const BrokenWrapper = (props) => <StyledText {...props} />
// MIT styleable - RICHTIG
const CorrectWrapper = StyledText.styleable((props, ref) => (
<StyledText ref={ref} {...props} />
))
// Jetzt funktioniert das:
const StyledCorrectWrapper = styled(CorrectWrapper, {
variants: {
bold: { true: { fontWeight: 'bold' } },
},
})
Hinzufügen zusätzlicher Props
Übergeben Sie ein generisches Typargument für zusätzliche Props:
type ExtraProps = { icon?: React.ReactNode }
const IconText = StyledText.styleable<ExtraProps>((props, ref) => {
const { icon, ...rest } = props
return (
<XStack>
{icon}
<StyledText ref={ref} {...rest} />
</XStack>
)
})
accept-Prop für benutzerdefinierte Komponenten
Ermöglicht Token/Theme-Auflösung bei nicht standardmäßigen Props:
// Für SVG fill/stroke, die Themenfarben akzeptieren sollen
const StyledSVG = styled(SVG, {}, {
accept: { fill: 'color', stroke: 'color' } as const,
})
// Verwendung: <StyledSVG fill="$blue10" />
// Für Style-Objekte (wie contentContainerStyle von ScrollView)
const MyScrollView = styled(ScrollView, {}, {
accept: { contentContainerStyle: 'style' } as const,
})
// Verwendung: <MyScrollView contentContainerStyle={{ padding: '$4' }} />
Wichtig: Verwenden Sie as const für das accept-Objekt.
Prop-Reihenfolge ist wichtig
Bei styled() bestimmt die Prop-Reihenfolge die Überschreibungspriorität:
// backgroundColor kann durch Props überschrieben werden
const Overridable = (props) => (
<View backgroundColor="$red10" {...props} width={200} />
)
// width kann NICHT überschrieben werden (kommt nach dem Spread)
// Variant-Reihenfolge ist auch wichtig:
<Component scale={3} huge /> // scale = 3 (scale kommt zuerst)
<Component huge scale={3} /> // scale = 2 (huge überschreibt)
Anti-Patterns
Dynamische Styles brechen Optimierung
// SCHLECHT - bricht Compiler-Optimierung
<View style={{ width: someVariable * 2 }} />
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />
// GUT - Variants verwenden
const Box = styled(View, {
variants: {
dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
},
})
<Box dark={isDark} />
Inline-Funktionen
// SCHLECHT - neue Funktion bei jedem Rendern
<View onPress={() => handlePress(id)} />
// GUT - stabile Referenz
const handlePressCallback = useCallback(() => handlePress(id), [id])
<View onPress={handlePressCallback} />
Falsche Import-Pfade
// Dies sind verschiedene Pakete mit unterschiedlichen Inhalten:
import { View } from 'tamagui' // Vollständiges UI-Kit
import { View } from '@tamagui/core' // Nur Core (kleiner)
import { Button } from '@tamagui/button' // Einzelne Komponente
// Wählen Sie einen Ansatz und bleiben Sie konsistent
Mischen von RN StyleSheet mit Tamagui
// SCHLECHT - StyleSheet-Werte lösen keine Token auf
const styles = StyleSheet.create({ box: { padding: 20 } })
<View style={styles.box} backgroundColor="$blue10" />
// GUT - alles Tamagui
<View padding="$4" backgroundColor="$blue10" />
Platform.OS-Verzweigung für Dialog/Sheet
// SCHLECHT - manuelle Plattform-Verzweigung
if (Platform.OS === 'web') {
return <Dialog>...</Dialog>
}
return <Sheet>...</Sheet>
// GUT - Adapt verwenden (siehe @DIALOG_PATTERNS.md)
<Dialog>
<Dialog.Portal>...</Dialog.Portal>
<Adapt when="sm" platform="touch">
<Sheet><Adapt.Contents /></Sheet>
</Adapt>
</Dialog>
Aktuelle Dokumentation abrufen
Für die neuesten API-Details rufen Sie Markdown-Dokumente direkt ab:
# Core-Dokumente
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"
# Komponenten-Dokumente
curl -sL "https://tamagui.dev/ui/sheet.md"
curl -sL "https://tamagui.dev/ui/dialog.md"
curl -sL "https://tamagui.dev/ui/select.md"
# Vollständiges Dokumentenverzeichnis
curl -sL "https://tamagui.dev/llms.txt"
Für HTML-Seiten verwenden Sie das web-fetch-Skill mit geeigneten Selektoren.
Kurzreferenz
Config v4 Kurzformen (Tailwind-konform)
| Kurzform | Eigenschaft |
|---|---|
bg | backgroundColor |
p | padding |
m | margin |
w | width |
h | height |
br | borderRadius |
Media Query Breakpoints
| Token | Standard | Server-Standard |
|---|---|---|
$xs | 660px | true |
$sm | 800px | false |
$md | 1020px | false |
$lg | 1280px | false |
$xl | 1420px | false |
Animationstreiber
| Treiber | Plattform | Anwendungsfall |
|---|---|---|
css | Web | Standard, beste Leistung |
react-native-reanimated | Nativ | Für native Animationen erforderlich |
Zusätzliche Musterdateien
- @DIALOG_PATTERNS.md - Dialog, Sheet, Adapt, Barrierefreiheit
- @FORM_PATTERNS.md - Form, Input, Label, Validierung mit zod
- @ANIMATION_PATTERNS.md - Animationstreiber, enterStyle/exitStyle
- @OVERLAY_PATTERNS.md - Popover, Tooltip, Select
- @COMPILER_PATTERNS.md - Details zur Compiler-Optimierung
- @DESIGN_SYSTEM.md - Design-Tokens und Theming