Host

一个跨平台的 Host 组件，用于包裹通用的 @expo/ui 内容。

Android

iOS

Web

Included in Expo Go

GitHub

npm

更新日志

Bundled version:

~56.0.6

一个用于通用 @expo/ui 内容的容器。在 Android 和 iOS 上，它会重新导出平台原生的 Jetpack Compose 的 Host/SwiftUI 的 Host，因此 Jetpack Compose/SwiftUI 子组件的渲染效果与它们在各自平台专用包中的表现完全一致。在 web 上，它会回退到 React Native 的 View。请将 Host 作为任何通用子树的根节点，以便同一组件树能够在这三个平台上正常工作。

安装

Terminal

- npx expo install @expo/ui

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

使用

基本用法

HostExample.tsx

import { Host, Column, Text, Button } from '@expo/ui';

export default function HostExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Column spacing={12} alignment="center">
        <Text>Hello, world!</Text>
        <Button label="Press me" onPress={() => alert('Pressed')} />
      </Column>
    </Host>
  );
}

匹配内容尺寸

使用 matchContents 让 Host 调整自身尺寸以适配其内容。在 Android 和 iOS 上，这会转发到平台原生的 Host（精确的平台语义请参见 Jetpack Compose/SwiftUI）。在 web 上，它会将 alignSelf: 'flex-start' 应用于底层 View，从而使宿主收缩以适配其子元素，而不是被父级拉伸。

注意：在 web 上，按轴形式（{ horizontal: true } / { vertical: true }）与布尔形式表现相同，因为 alignSelf 只控制父级交叉轴上的拉伸。依赖独立按轴尺寸调整的组件应当预期在 web 上无论选择哪一个轴，都会有相同的自适应收缩行为。

MatchContentsExample.tsx

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

export default function MatchContentsExample() {
  return (
    <Host matchContents>
      <Button label="Sized to content" onPress={() => {}} />
    </Host>
  );
}

布局方向

使用 layoutDirection 将子树渲染为从左到右或从右到左。在 Android 和 iOS 上，这会转发到平台原生的 Host（精确的平台语义请参见 Jetpack Compose/SwiftUI）。在 web 上，它会在底层 View 上设置 dir 属性，从而让后代继承所选方向。

LayoutDirectionExample.tsx

import { Host, Row, Text } from '@expo/ui';

export default function LayoutDirectionExample() {
  return (
    <Host layoutDirection="rightToLeft">
      <Row spacing={8}>
        <Text>First</Text>
        <Text>Second</Text>
      </Row>
    </Host>
  );
}

响应内容布局

使用 onLayoutContent 来在宿主内容当前尺寸发生变化时接收通知。在 Android 和 iOS 上，这会转发到平台原生的 Host（精确的平台语义请参见 Jetpack Compose/SwiftUI）。在 web 上，它来源于底层 View 的 onLayout 回调。

OnLayoutContentExample.tsx

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

export default function OnLayoutContentExample() {
  return (
    <Host
      matchContents
      onLayoutContent={({ nativeEvent: { width, height } }) =>
        console.log(`内容尺寸：${width}x${height}`)
      }>
      <Text>Hello, world!</Text>
    </Host>
  );
}

填充视口

对于应该占据可用视口空间的内容，请使用 useViewportSizeMeasurement。在 Android 和 iOS 上，这会转发到平台原生的 Host（精确的平台语义请参见 Jetpack Compose/SwiftUI）。在 web 上，宿主底层的 View 会获得当前窗口的宽度和高度；你传入的任何显式 style 仍然优先生效。

UseViewportSizeMeasurementExample.tsx

import { Host, Column, Text } from '@expo/ui';

export default function UseViewportSizeMeasurementExample() {
  return (
    <Host useViewportSizeMeasurement>
      <Column spacing={12} alignment="center">
        <Text>填充视口</Text>
      </Column>
    </Host>
  );
}

忽略安全区域

默认情况下，Host 会尊重设备的安全区域内边距（刘海、Home 指示条等）。使用 ignoreSafeArea="all" 可让内容延伸到边缘到边缘，或使用 ignoreSafeArea="keyboard" 保留安全区域内边距但忽略键盘内边距。在 Android 和 iOS 上，这会转发到平台原生的 Host（精确的平台语义请参见 Jetpack Compose/SwiftUI）。在 web 上，它通过将 CSS env(safe-area-inset-*) 值作为底层 View 的内边距来实现；默认情况下还会为启用了 VirtualKeyboard API 的页面合并 env(keyboard-inset-*)。

IgnoreSafeAreaExample.tsx

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

export default function IgnoreSafeAreaExample() {
  return (
    <Host ignoreSafeArea="all">
      <Text>延伸到刘海和 Home 指示条后方</Text>
    </Host>
  );
}

强制使用颜色方案

使用 colorScheme 覆盖后代原生视图的外观。传入 'light' 或 'dark' 可强制指定其中一种，或者省略它以跟随设备设置。仅限 Android 和 iOS —— 在 web 上会被忽略。

HostColorSchemeExample.tsx

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

export default function HostColorSchemeExample() {
  return (
    <Host colorScheme="dark" style={{ flex: 1 }}>
      <Button label="始终为深色" onPress={() => {}} />
    </Host>
  );
}

API

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

Component

`Host`

Android

iOS

Web

Type: React.Element<UniversalHostProps>

A bridging container that hosts SwiftUI views on iOS and Jetpack Compose views on Android. On platforms without a native UI-toolkit binding (web, RN fallback), renders a plain View. The colorScheme, layoutDirection, and matchContents props are accepted for API parity but have no effect.

Props

`children`

Android

iOS

Web

Optional • Type: ReactNode

`colorScheme`

Android

iOS

Optional • Type: ColorSchemeName

The color scheme to apply to descendant native views. 'light' / 'dark' force a specific appearance; omitted follows the device setting.

`ignoreSafeArea`

Android

iOS

Web

Optional • Literal type: string

Controls which safe area regions the hosting view should ignore. Can only be set once on mount.

'all'- ignores all safe area insets.
'keyboard' - ignores only the keyboard safe area.

Acceptable values are: 'all' | 'keyboard'

`layoutDirection`

Android

iOS

Web

Optional • Literal type: string

Layout direction for the platform UI content. Defaults to the current locale direction from I18nManager.

Acceptable values are: 'leftToRight' | 'rightToLeft'

`matchContents`

Android

iOS

Web

Optional • Literal type: union • Default: false

When true, the host updates its size in the React Native view tree to match the content's layout from the underlying platform UI toolkit. Can only be set once on mount.

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

`onLayoutContent`

Android

iOS

Web

Optional • Type:

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

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

`useViewportSizeMeasurement`

Android

iOS

Web

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 layout. This is particularly useful for views that need to fill their available space, such as List.

Inherited Props

ViewProps