Reference version

This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Expo UI

一组组件,可让你直接使用 Jetpack Compose 和 SwiftUI 从 React 构建 UI。

Android
iOS
tvOS
Included in Expo Go
Recommended version:
~57.0.18

@expo/ui 是一组原生输入组件,允许你使用 Jetpack Compose 和 SwiftUI 构建完全原生的界面。它旨在提供典型应用所需的常用功能和组件。

功能

  • 原生基元:Expo UI 并非又一个 UI 库,而是将 Jetpack Compose 和 SwiftUI 基元引入 React Native。
  • 一对一映射:组件与对应的原生组件一一映射。若要浏览 Jetpack Compose 和 SwiftUI 组件目录,请参见下文的可用组件。
  • 支持完整应用:Expo UI 在组件级别集成。你可以用它编写整个应用,也可以一次只在一个屏幕中采用它。你还可以混用 React Native 组件、DOM 组件以及使用 react-native-skia 绘制的 2D 组件。

可用平台

组件可用于以下平台:

  • Jetpack Compose:使用 Jetpack Compose 组件构建原生 Android 界面
  • SwiftUI:使用 SwiftUI 组件构建原生 iOS 界面
  • 通用:可在 Android、iOS 和 Web 上运行的跨平台组件,单一源码即可实现。

如果你希望使用一棵无需修改即可在 Android、iOS 和 Web 上运行的组件树,请从**通用**组件开始。如果你需要通用 API 未涵盖的平台专属控件、修饰符或行为,请直接使用 Jetpack Compose 或 SwiftUI。

即插即用替代方案

参见 即插即用替代方案,了解与 API 兼容的替代方案,这些方案可替代常见的 React Native 社区库。

面向 AI 智能体的 Expo Skills

如果你使用 AI 智能体,请安装 Expo Skills,教它如何构建具有原生体验的屏幕:

expo-ui

Build native UI with the @expo/ui package: real SwiftUI on iOS and Jetpack Compose on Android.

expo-native-ui

Build beautiful, native-feeling Expo screens.

可用组件

Jetpack Compose

SwiftUI

可直接替换的组件

通用

常见问题

我可以在 Expo UI 组件中使用 flexbox 或其他样式吗?

Flexbox 样式适用于 Host 组件本身。进入原生上下文后,Yoga 将不可用。在 Android 上使用 Row 和 Column 定义布局,在 iOS 上则使用 HStack 和 VStack。

什么是 Host 组件?

Host 是 React Native 与原生 UI 工具包之间的桥梁。每个 Expo UI 组件都必须包裹在其中。你可以将它理解为 DOM 中的 <svg>,或 react-native-skia 中的 <Canvas>。在 iOS 上,它使用 UIHostingController 在 UIKit 中渲染 SwiftUI 视图。有关跨平台用法,请参见通用版 Host。

Expo UI 与 react-native-paper 或 react-native-elements 等库有什么区别?

Expo UI 不是“又一个”UI 库,也不是带有固定设计理念的设计套件,而是一个基元库。它直接向 JavaScript 暴露原生 Jetpack Compose 和 SwiftUI 组件,而不是在 JavaScript 中重新实现或模拟 UI。

我可以在 Android 或 Web 上使用 @expo/ui/swift-ui 吗?

不可以。@expo/ui/swift-ui 会渲染 SwiftUI 视图,而 SwiftUI 视图仅存在于 Apple 平台上。在 Android 上使用 @expo/ui/jetpack-compose。如果你希望为 Android、iOS 和 Web 使用同一棵组件树,请使用通用组件。

我可以在 SwiftUI 组件中使用 React Native 组件吗?

可以,你可以将 React Native 组件作为 JSX 子元素放入 Expo UI 组件中。Expo UI 会自动为你创建 UIViewRepresentable 包装器。 不过请注意,SwiftUI 布局系统的工作方式与 UIKit 不同,并且存在一些限制。根据 Apple 的文档:

还请注意,一旦渲染 React Native 组件,你就离开了 SwiftUI 上下文。若要再次添加 Expo UI 组件,请重新引入 Host 包装器。

让 SwiftUI 布局保持独立。虽然可以进行互操作,但清晰定义边界时效果最好。

我是 Jetpack Compose 或 SwiftUI 开发者。为什么要学习 Expo UI?

React 的 “学一次,随处编写” 承诺现在也扩展到了 Jetpack Compose 和 SwiftUI。你可以运用已有知识,在 React Native 生态系统中构建应用。同一个应用还可以通过 DOM 组件扩展到 Web,并使用 react-native-skia 添加 2D 渲染,或使用 react-native-webgpu 添加 3D 渲染。由于集成是在组件级别实现的,你的应用可以在不同部分采用不同方案。

其他资源

Expo UI 示例

最新的 Expo UI 示例。

Hot Chocolate 应用示例

一个使用 Expo UI 复刻 YVR Hot Chocolate Fest 应用的示例应用。

Expo UI 多平台演示

一个演示生产就绪的 Expo UI 软件包的项目,该软件包适用于 SDK 56 及更高版本。该项目可在电视(Android TV、Apple TV)和移动设备(Android、iOS)上运行。演示屏幕涵盖了 Jetpack Compose 和 SwiftUI 中的大多数可用组件。