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 内容的容器。在 Android 和 iOS 上，它会重新导出平台原生的 Host 用于 Jetpack Compose/Host 用于 SwiftUI，因此 Jetpack Compose/SwiftUI 的子组件的渲染效果与在平台特定包中完全相同。在 Web 上，它会退回到 React Native View。将 Host 用作任何通用子树的根节点，这样相同的组件树可以在所有三个平台上使用。

🌐 A container for universal @expo/ui content. On Android and iOS it re-exports the platform-native Host for Jetpack Compose/Host for SwiftUI, so Jetpack Compose/SwiftUI children render exactly as they would in the platform-specific packages. On web, it falls back to a React Native View. Use Host as the root of any universal subtree so the same component tree works across all three platforms.

安装

🌐 Installation

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

用法

🌐 Usage

基本用法

🌐 Basic usage

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>
  );
}

匹配内容大小

🌐 Match contents sizing

使用 matchContents 让 Host 根据其内容调整自身大小。在 Android 和 iOS 上，这会被转发到平台本地的 Host（具体的平台语义请参见 Jetpack Compose/SwiftUI）。在网页上，它会将 alignSelf: 'flex-start' 应用于底层的 View，使宿主根据其子元素缩小以适应，而不是被父元素拉伸。

🌐 Use matchContents to let Host size itself to fit its content. On Android and iOS, this is forwarded to the platform-native Host (see Jetpack Compose/SwiftUI for the exact platform semantics). On web, it applies alignSelf: 'flex-start' to the underlying View so the host shrinks to fit its children instead of being stretched by its parent.

注意: 在网页上，每轴形式（{ horizontal: true } / { vertical: true }）的行为与布尔形式相同，因为 alignSelf 仅控制父元素交叉轴上的拉伸。依赖独立每轴尺寸的组件应该预期，无论选择哪个轴，在网页上都会有相同的收缩适应行为。

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

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

布局方向

🌐 Layout direction

使用 layoutDirection 将子树渲染为从左到右或从右到左。在 Android 和 iOS 上，这会被转发到平台本地的 Host（查看 Jetpack Compose/SwiftUI 了解具体平台语义）。在网页上，它会在底层的 View 上设置 dir 属性，使子代继承所选方向。

🌐 Use layoutDirection to render the subtree as left-to-right or right-to-left. On Android and iOS, this is forwarded to the platform-native Host (see Jetpack Compose/SwiftUI for the exact platform semantics). On web, it sets the dir attribute on the underlying View so descendants inherit the chosen direction.

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>
  );
}

对内容布局做出反应

🌐 Reacting to content layout

使用 onLayoutContent 来接收主机内容当前尺寸的通知。在 Android 和 iOS 上，这会被转发到平台原生的 Host（有关具体平台语义，请参见 Jetpack Compose/SwiftUI）。在网页上，它是从底层 View 的 onLayout 回调中派生的。

🌐 Use onLayoutContent to be notified of the current dimensions of the host's content. On Android and iOS, this is forwarded to the platform-native Host (see Jetpack Compose/SwiftUI for the exact platform semantics). On web, it is derived from the underlying View's onLayout callback.

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

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

填充视口

🌐 Filling the viewport

对于应根据可用视口空间调整大小的内容，请使用 useViewportSizeMeasurement。在 Android 和 iOS 上，这将被转发到平台本地的 Host（准确的 平台语义请参见 Jetpack Compose/SwiftUI）。在网页上，宿主的底层 View 会被赋予当前窗口的宽度和高度；你传递的任何显式 style 仍然优先。

🌐 Use useViewportSizeMeasurement for content that should size to the available viewport space. On Android and iOS, this is forwarded to the platform-native Host (see Jetpack Compose/SwiftUI for the exact platform semantics). On web, the host's underlying View is given the current window's width and height; any explicit style you pass still wins.

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

export default function UseViewportSizeMeasurementExample() {
  return (
    <Host useViewportSizeMeasurement>
      <Column spacing={12} alignment="center">
        <Text>Fills the viewport</Text>
      </Column>
    </Host>
  );
}

忽略安全区域

🌐 Ignoring safe areas

默认情况下，Host 会遵循设备的安全区域内边距（刘海、主屏手势指示器等）。使用 ignoreSafeArea="all" 可以让内容延伸到屏幕边缘，或者使用 ignoreSafeArea="keyboard" 保留安全区内边距但忽略键盘内边距。在 Android 和 iOS 上，这会转发到平台原生的 Host（具体平台语义请参见 Jetpack Compose/SwiftUI）。在网页上，它是通过将 CSS env(safe-area-inset-*) 值作为底层 View 的内边距来实现的；默认情况下，对于选择使用 VirtualKeyboard API 的页面，也会包含 env(keyboard-inset-*)。

🌐 By default, Host respects the device safe area insets (notch, home indicator, and so on). Use ignoreSafeArea="all" to let content extend edge-to-edge, or ignoreSafeArea="keyboard" to keep safe-area padding but ignore the keyboard inset. On Android and iOS, this is forwarded to the platform-native Host (see Jetpack Compose/SwiftUI for the exact platform semantics). On web, it is implemented via the CSS env(safe-area-inset-*) values applied as padding on the underlying View; the default also folds in env(keyboard-inset-*) for pages that opt in to the VirtualKeyboard API.

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

export default function IgnoreSafeAreaExample() {
  return (
    <Host ignoreSafeArea="all">
      <Text>Extends behind the notch and home indicator</Text>
    </Host>
  );
}

强制颜色方案

🌐 Forcing a color scheme

使用 colorScheme 来覆盖后代原生视图的外观。传入 'light' 或 'dark' 可以强制使用其中之一，或者省略它以遵循设备设置。仅适用于 Android 和 iOS——在网页上会被忽略。

🌐 Use colorScheme to override the appearance of descendant native views. Pass 'light' or 'dark' to force one, or omit it to follow the device setting. Android and iOS only — ignored on web.

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

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

应用接口

🌐 API

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

Component

Props