主机

一个 SwiftUI 主机组件，使 SwiftUI 组件能够在 React Native 中使用。

iOS

tvOS

Included in Expo Go

Recommended version:

~57.0.22

信息有关跨平台使用，请参阅通用 Host —— 它会根据平台呈现相应的原生组件。

一个组件，允许你在 React Native 中放置其他 @expo/ui/swift-ui 组件。它的作用类似于 DOM 的 <svg>，react-native-skia 的 <Canvas>，其底层使用 UIHostingController 在 UIKit 中渲染 SwiftUI 视图。

🌐 A component that allows you to put the other @expo/ui/swift-ui components in React Native. It acts like <svg> for DOM, <Canvas> for react-native-skia, which underlying uses UIHostingController to render the SwiftUI views in UIKit.

由于 Host 组件是一个 React Native View，你可以向它传递 style 属性，或者传递 matchContents 属性，使 Host 组件匹配内容的大小。

🌐 Since the Host component is a React Native View, you can pass the style prop to it or matchContents prop to make the Host component match the contents' size.

安装

🌐 Installation

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

🌐 Usage

匹配内容大小

🌐 Match contents sizing

使用 matchContents 让 Host 自动调整大小以适应其 SwiftUI 内容，而不需要明确的尺寸。

🌐 Use matchContents to let the Host automatically size itself to fit its SwiftUI content, instead of requiring explicit dimensions.

注意: matchContents 仅对具有固有尺寸或明确 frame 的组件正确工作（例如，Button、Toggle、Text）。像 Slider 和线性 ProgressView 这样的可伸缩宽度组件会扩展以填充可用空间，并且没有固有宽度，对它们使用 matchContents 将导致几乎为零的宽度。对于这些组件，要么在组件上应用 frame 修饰符以给它一个明确的宽度，要么在 Host 上使用 style 进行明确大小设置（例如，style={{ flex: 1 }} 或 style={{ width: 300 }}）。

MatchContentsExample.tsx

import { Button, Host } from '@expo/ui/swift-ui';

export default function MatchContentsExample() {
  return (
    <Host matchContents>
      <Button
        onPress={() => {
          console.log('Pressed');
        }}
        label="Click"
      />
    </Host>
  );
}

注意：不要在与滚动容器（ScrollView、List、Form、LazyHStack、LazyVStack）相同的轴上使用 matchContents。matchContents 对应 SwiftUI 的 .fixedSize，它会根据内容调整滚动容器的大小。它还会导致视口之外没有可滚动的内容，因此滚动会悄无声息地停止工作。请将 matchContents={{ vertical: true }} 与 style={{ width: '100%' }}（或滚动轴上的任何有限宽度）一起使用。

ScrollViewMatchContents.tsx

import { Host, HStack, ScrollView, Text } from '@expo/ui/swift-ui';

export default function ScrollViewMatchContents() {
  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <ScrollView axes="horizontal">
        <HStack spacing={12}>
          {Array.from({ length: 20 }).map((_, i) => (
            <Text key={i}>Item {i}</Text>
          ))}
        </HStack>
      </ScrollView>
    </Host>
  );
}

使用样式进行显式设置大小

🌐 Explicit sizing with style

使用 style 来设置 Host 的明确大小，例如使用 flex: 1 填充可用空间。

🌐 Use style to set explicit sizes on the Host, such as filling the available space with flex: 1.

ExplicitSizingExample.tsx

import { Button, Host, VStack, Text } from '@expo/ui/swift-ui';

export default function ExplicitSizingExample() {
  return (
    <Host style={{ flex: 1 }}>
      <VStack spacing={8}>
        <Text>Hello, world!</Text>
        <Button
          onPress={() => {
            console.log('Pressed');
          }}
          label="Click"
        />
      </VStack>
    </Host>
  );
}

在 React Native 视图中放置组件

🌐 Placing components inside React Native views

Host 用 SwiftUI 渲染它的子视图。在 Host 内部的 React Native 视图（比如 View 或 ScrollView）会切换回 React Native 渲染。要在该视图内使用 SwiftUI 组件，需要将组件封装在一个新的 Host 里。即便树中更高的 Host 封装了该视图，也要这么做。

ReactNativeLayoutExample.tsx

import { useState } from 'react';
import { ScrollView, Text, View } from 'react-native';
import { Host, Toggle } from '@expo/ui/swift-ui';

export default function ReactNativeLayoutExample() {
  const [isOn, setIsOn] = useState(false);

  return (
    <ScrollView>
      <View
        style={{
          flexDirection: 'row',
          alignItems: 'center',
          justifyContent: 'space-between',
          padding: 16,
        }}>
        <Text>Notifications</Text>
        <Host matchContents>
          <Toggle isOn={isOn} onIsOnChange={setIsOn} />
        </Host>
      </View>
    </ScrollView>
  );
}

要在 SwiftUI 组件中放置 React Native 视图，请使用 RNHostView。

🌐 To place React Native views inside SwiftUI components, use RNHostView.

忽略键盘安全区域

🌐 Ignoring keyboard safe area

当 React Native 已经处理键盘避免（例如使用 react-native-keyboard-controller）时，使用 ignoreSafeArea="keyboard"，以防止 SwiftUI 宿主应用自身的键盘内边距。

🌐 Use ignoreSafeArea="keyboard" when React Native is already handling keyboard avoidance (for example, with react-native-keyboard-controller), to prevent the SwiftUI host from applying its own keyboard inset.

IgnoreKeyboardExample.tsx

import { Host, TextField } from '@expo/ui/swift-ui';
import {
  KeyboardProvider,
  KeyboardStickyView,
} from 'react-native-keyboard-controller';
import { View } from 'react-native';

export default function IgnoreKeyboardExample() {
  return (
    <KeyboardProvider>
      <View style={{ flex: 1, backgroundColor: 'black' }}>
        <KeyboardStickyView
          style={{
            position: 'absolute',
            bottom: 0,
            left: 0,
            right: 0,
            padding: 16,
            backgroundColor: 'green',
          }}>
          <Host
            matchContents
            ignoreSafeArea="keyboard"
            style={{ backgroundColor: 'red' }}>
            <TextField placeholder="Enter text" axis="vertical" />
          </Host>
        </KeyboardStickyView>
      </View>
    </KeyboardProvider>
  );
}

忽略容器安全区域

🌐 Ignoring the container safe area

使用 ignoreSafeArea="container" 只移除容器安全区（刘海、首页指示器、状态栏和导航栏）。键盘的安全区仍然适用。

🌐 Use ignoreSafeArea="container" to remove only the container safe area (notch, home indicator, status and navigation bars). The keyboard safe area still applies.

IgnoreContainerSafeAreaExample.tsx

import { Button, Host, HStack, Spacer } from '@expo/ui/swift-ui';
import { labelStyle } from '@expo/ui/swift-ui/modifiers';
import { useSafeAreaInsets } from 'react-native-safe-area-context';

export default function IgnoreContainerSafeAreaExample() {
  const insets = useSafeAreaInsets();
  return (
    <Host
      style={{ width: '100%', paddingTop: insets.top }}
      matchContents={{ vertical: true }}
      ignoreSafeArea="container">
      <HStack>
        <Button
          systemImage="chevron.backward"
          label="Back"
          modifiers={[labelStyle('iconOnly')]}
        />
        <Spacer />
        <Button
          systemImage="square.and.arrow.up"
          label="Share"
          modifiers={[labelStyle('iconOnly')]}
        />
      </HStack>
    </Host>
  );
}

忽略所有安全区域

🌐 Ignoring all safe areas

当你希望 SwiftUI 内容延伸到状态栏和键盘后面时，可以使用 ignoreSafeArea="all"，这对于全屏覆盖或背景很有用。

🌐 Use ignoreSafeArea="all" when you want SwiftUI content to extend behind the status bar and the keyboard, useful for full-screen overlays or backgrounds.

IgnoreAllSafeAreasExample.tsx

import { Host, Text, VStack } from '@expo/ui/swift-ui';

export default function IgnoreAllSafeAreasExample() {
  return (
    <Host
      ignoreSafeArea="all"
      style={{
        position: 'absolute',
        top: 0,
        left: 0,
        right: 0,
        bottom: 0,
      }}>
      <VStack>
        <Text>
          This content extends behind the status bar and home
          indicator.
        </Text>
      </VStack>
    </Host>
  );
}

应用接口

🌐 API

import { Host } from '@expo/ui/swift-ui';

Component

`Host`

iOS

tvOS

Type: React.Element<HostProps>

A hosting component for SwiftUI views.

HostProps

`children`

iOS

tvOS

Type: ReactNode

`colorScheme`

iOS

tvOS

Optional • Literal type: string

The color scheme of the host view.

Acceptable values are: 'light' | 'dark'

`ignoreSafeArea`

iOS

tvOS

Optional • Literal type: string

Controls which safe area regions the SwiftUI hosting view should ignore.

'all' - ignores all safe area insets, including the keyboard.
'container' - ignores only the container safe area (notch, home indicator, status and navigation bars). The keyboard safe area still applies.
'keyboard' - ignores only the keyboard safe area.

Acceptable values are: 'container' | 'all' | 'keyboard'

`layoutDirection`

iOS

tvOS

Optional • Literal type: string

The layout direction for the SwiftUI content. Defaults to the current locale direction from I18nManager.

Acceptable values are: 'leftToRight' | 'rightToLeft'

`matchContents`

iOS

tvOS

Optional • Literal type: union • Default: false

When true, the host view will update its size in the React Native view tree to match the content's layout from SwiftUI. Can be only set once on mount.

Acceptable values are: boolean | { horizontal: boolean, vertical: boolean }

`onLayoutContent`

iOS

tvOS

Optional • Type:

(event: {
  nativeEvent: {
  height: number, 
  width: number
}
}) => void

Callback function that is triggered when the SwiftUI content completes its layout. Provides the current dimensions of the content, which may change as the content updates.

`pointerEvents`

iOS

tvOS

Optional • Literal type: string

Acceptable values are: 'auto' | 'box-none' | 'none' | 'box-only'

`seedColor`

iOS

tvOS

Optional • Type: ColorValue

Seed color applied to the SwiftUI content as its tint. It propagates through the SwiftUI environment to theme interactive elements (buttons, switches, sliders, and similar controls) rendered by the children.

`style`

iOS

tvOS

Optional • Type: StyleProp<ViewStyle>

`useViewportSizeMeasurement`

iOS

tvOS

Optional • Type: boolean • Default: false

When true and no explicit size is provided, the host will use the viewport size as the proposed size for SwiftUI layout. This is particularly useful for SwiftUI views that need to fill their available space, such as Form.

Inherited props

CommonViewModifierProps