# 以太-ui iOS 第一个 React Native 组件库，作为 Expo 的 Tailwind CSS / NativeWind 预设构建。所有组件都使用“tailwind-variants”进行样式设置，并使用 NativeWind CSS 变量进行主题设置。 ## 仅限 iOS 该库专门针对 **iOS**。 Android 和 Web 不受支持，将来也不会支持。不要添加平台检查或跨平台回退。 ## 进口所有组件都从主入口点命名为导出：从“@byarcadia-app/aether”导入{ Button、ButtonLabel、Card、CardHeader、Text }；图标是一个单独的入口点：从“@byarcadia-app/aether/icons”导入{ IconSymbol }； ## 组件目录 ### 版式 **标题** — H1–H4 组件遵循 iOS 人机界面指南调整大小。具有可配置粗细的 Inter 字体系列。 → 阅读 `references/heading.md` 了解完整的 API **文本** - 具有大小变体（lg、md、sm、xs）和粗细变体（常规、中等、半粗体、粗体）的正文组件。 → 阅读 `references/text.md` 了解完整的 API **标题** — 两种尺寸的小辅助文本（md、sm）。默认情况下使用柔和的前景色。 → 阅读 `references/caption.md` 了解完整的 API ### 按钮 **按钮** - 主要交互元素有 5 个变体：“主要”、“次要”、“轮廓”、“幽灵”、“破坏性”。支持闪光效果、带有旋转器的加载状态、触觉反馈和按下动画。具有“ButtonLabel”和“ButtonShimmer”的复合组件。 → 阅读 `references/button.md` 了解完整的 API **GlassButton** — 使用 `@callstack/liquid-glass` 的 iOS 26+ LiquidGlass 按钮。在旧版 iOS 版本上自动回退到标准主按钮。用于适合半透明玻璃效果的英雄动作。 → 阅读 `references/glass-button.md` 了解完整的 API **HighlightTappable** — 轻量级按键反馈包装器，可在触摸时显示微妙的背景突出显示。用于不需要完整按钮样式的自定义可点击区域。 → 阅读 `references/highlight-tappable.md` 了解完整的 API ### 表格 **TextField** - 具有子组件的复合输入组件：`TextFieldLabel`、`TextFieldInput`、`TextFieldInputStartContent`、`TextFieldInputEndContent`、`TextFieldDescription`、`TextFieldErrorMessage`。具有动画焦点边框、可清除输入、多行模式和验证错误显示。 → 阅读 `references/text-field.md` 了解完整的 API **ErrorView** — 有条件的错误消息显示。当提供错误字符串时，呈现带有危险颜色的错误消息；当错误未定义/为空时，不呈现任何内容。 → 阅读 `references/error-view.md` 了解完整的 API ### 布局和结构 **VStack / HStack** — 多态 Flexbox 布局基元。 VStack 垂直排列子级，HStack 水平排列。接受 `as` 属性以呈现为任何 React Native 组件（View、ScrollView、Pressable 等）。 → 阅读 `references/layout.md` 了解完整的 API **Card** — 具有子组件的复合卡片组件：`CardHeader`、`CardTitle`、`CardDescription`、`CardBody`、`CardImage`、`CardFooter`。可选择通过“onPress”道具通过触觉反馈进行按压。使用基于表面的“变体”（“solid”、“glass”、“fog”）和“level”来实现视觉层次结构。 → 阅读 `references/card.md` 了解完整的 API **表面** - 具有视觉层次结构支持的分层背景容器。三种变体：“固体”（不透明）、“玻璃”（半透明模糊）、“雾”（微妙渐变）。表面通过“level”道具根据嵌套深度自动变暗。 → 阅读 `references/surface.md` 了解完整的 API **列表** - 遵循 iOS 设置模式的复合列表组件。子组件：`ListItem`、`ListItemContent`、`ListItemIcon`、`ListItemAccessory`、`ListSectionHeader`、`ListItemChevron`（动画旋转）、`ListItemCollapse`（动画展开/折叠）。项目支持按突出显示和导航 V 形。 → 阅读 `references/list.md` 了解完整的 API ### 反馈 **骨架** — 具有主题感知颜色的脉冲加载占位符。渲染在两个不透明度值之间脉动的圆角矩形。尊重全局动画禁用状态（动画关闭时显示静态块）。 → 阅读 `references/sculpture.md` 了解完整的 API **ScrollFade** — 滚动容器边缘的渐变淡入淡出叠加。放置为 ScrollView 的同级，并使用“position=”top”或“position=”bottom”来定位滚动边界处的内容。 → 阅读 `references/scroll-fade.md` 了解完整的 API **AnimationWrapper** - 使用 `react-native-reanimated` 的声明式进入/退出/布局动画包装器。通过 props 配置进入、退出和布局转换。消费者控制——不受全局动画禁用状态的影响。 → 阅读 `references/animation-wrapper.md` 了解完整的 API ### 图标 **IconSymbol** — 适用于 iOS 的 SF 符号组件。需要“expo-symbols”（可选的对等依赖）。可从单独的入口点获取：`import { IconSymbol } from "@byarcadia-app/aether/icons"`。支持符号粗细、比例和主题颜色集成。 → 阅读 `references/icon-symbol.md` 了解完整的 API ## 复合组件模式 Card、TextField 和 List 是**复合组件** — 它们使用作为子组件而不是配置属性组成的子组件。所有子组件都是**平面命名的导出** - 直接导入它们（例如，`import { Card, CardHeader, CardTitle } from "@byarcadia-app/aether"`）。在内部，每个都有一个像“Aether.Card.CardTitle”一样的“displayName”，由“getElementByDisplayName()”用来提取和定位子项。 <卡片> <卡片标题> 帐户设置管理您的偏好 <卡体> 内容在此处 <卡页脚> <按钮变体=“primary”> 保存 <文本字段> 电子邮件 <文本字段输入占位符=“you@example.com” 键盘类型=“电子邮件地址” 自动大写=“无” /> {errors.email} ## 造型系统所有组件样式都使用 `tailwind-variants` 包中的 `tailwind-variants` (`tv()`)。变体常量导出为命名导出以供外部访问（例如“buttonVariants”、“textVariants”）。 **类名实用程序：** * `cn(...classes)` — 快速字符串连接。没有冲突解决。用于简单串联。 * `cnx(...classes)` — 通过 `tailwind-merge` 与 Tailwind 冲突解决合并。 **在从组件 props 接受 `className` 时更喜欢这个**以避免类冲突。 **自定义调色板：** 将 `colorPalette` 属性传递给 `AetherProvider` 以覆盖默认颜色标记。这会为浅色和深色主题注入自定义 CSS 变量。 → 阅读 `references/utilities.md` 了解完整的实用 API ## 颜色标记基于HSLA的语义颜色系统。颜色是运行时通过 NativeWind `vars()` API 生成的 CSS 变量。 **基础代币：** * `background` / `foreground` - 应用程序背景和主要文本 * `surface` - 卡片和容器背景 * `overlay` - 模态/工作表叠加 **语义标记**（每个都有一个“-foreground”变体，用于彩色背景上的文本）： * `primary` / `Secondary` — 品牌和次要行动 * `success` / `warning` / `danger` / `info` — 状态颜色 **用户界面令牌：** * `muted` - 微妙的背景和辅助文本（`muted-foreground`） * `border` - 默认边框颜色 * `input` - 输入字段边框 * `ring` - 聚焦环颜色 **特殊代币：** * `glass` / `glass-border` / `glass-highlight` — 玻璃效果颜色 * 标签颜色：`tag-coral`、`tag-amber`、`tag-sky`、`tag-lavender`、`tag-slate`、`tag-mint`、`tag-stone`（每个都有 `-foreground`） **Tailwind 类中的用法：** bg-primary — 主要背景 text-foreground - 默认文本颜色 text-danger-foreground — 危险色背景上的文本 border-border — 默认边框 bg-muted — 微妙的背景 → 阅读 `references/colors.md` 以获取完整的标记表 ## 钩子 * `useInterFonts()` — 加载 Inter 字体系列。返回 `{ fontsLoaded: boolean, fontError: Error |空}`。在渲染组件之前调用根布局。 * `useColorScheme()` — 获取当前的配色方案。返回“浅色”或“深色”。 * `useThemeColor(token, opts?)` — 将语义颜色标记解析为其运行时 HSLA 字符串值。对于需要原始颜色值的地方（例如 StatusBar、本机 API）很有用。 * `useNavigationTheme()` — 返回应用了以太颜色的 React Navigation `Theme` 对象。传递到``。 * `useAnimationDisabled()` — 当全局禁用动画时返回 `true`（通过 AetherProvider 或 iOS 减少运动设置上的 `disableAnimations` 属性）。 → 阅读 `references/hooks.md` 以获取完整的钩子签名和示例 ## 触觉该包导出 `hapticsImpact(style: HapticFeedbackStyle)` 用于触发触觉反馈。 “Button”组件有一个内置的“haptics”道具，可以自动处理这个问题。在构建需要触觉反馈的自定义交互式组件时，直接使用“hapticsImpact()”。 ## 提供商设置所有以太组件都需要位于应用程序根目录的“AetherProvider”。它由主题注入、动画控制和全局文本配置组成。关键道具： * `colorPalette` - 自定义浅色/深色覆盖 * `disableAnimations` — 全局禁用所有动画（也尊重 iOS 减少运动） * `allowFontScaling` — 控制文本字体缩放（默认值：`true`） * `maxFontSizeMultiplier` - 大写字体缩放乘数 → 阅读 `references/provider.md` 了解完整的配置选项

以太用户界面

包含技能