Host

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

Android

iOS

Web

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~57.0.0

一个用于通用 @expo/ui 内容的容器。在 Android 和 iOS 上，它会重新导出平台原生的 Host for Jetpack Compose/Host for SwiftUI，因此 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>你好，世界！</Text>
        <Button label="点我" onPress={() => alert('已点击')} />
      </Column>
    </Host>
  );
}

使内容尺寸匹配

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

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

MatchContentsExample.tsx

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

export default function MatchContentsExample() {
  return (
    <Host matchContents>
      <Button label="根据内容调整尺寸" 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>第一个</Text>
        <Text>第二个</Text>
      </Row>
    </Host>
  );
}

响应内容布局

使用 onLayoutContent 以获取 host 内容当前的尺寸变化通知。在 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>你好，世界！</Text>
    </Host>
  );
}

填充视口

对于应按可用视口空间进行尺寸调整的内容，请使用 useViewportSizeMeasurement。在 Android 和 iOS 上，这会转发到平台原生的 Host（精确的平台语义请参见 Jetpack Compose/SwiftUI）。在 web 上，host 底层的 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 的内边距来实现；默认情况下还会将 env(keyboard-inset-*) 叠加到为采用 VirtualKeyboard API 的页面所使用的内边距中。

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.

Props

`children`

Android

iOS

Web

Optional • Type: ReactNode

`colorScheme`

Android

iOS

Web

Optional • Type: ColorSchemeName

The color scheme to apply to the subtree. '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.

`seedColor`

Android

iOS

Web

Optional • Type: ColorValue

Seed color used to derive the theme applied to the host's subtree. Each platform interprets it natively:

On Android, it generates a full Material 3 palette (SchemeTonalSpot, the same algorithm as Material You) that themes Compose children and is exposed to descendants via useMaterialColors().
On iOS, it is applied as the SwiftUI tint, propagating through the environment to theme interactive controls such as buttons, switches, and sliders.
On web, it generates a primary color scale exposed as CSS variables to the subtree.

When omitted, each platform falls back to its default theme.

`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