按钮

用于显示原生 Material3 按钮的 Jetpack Compose 按钮组件。

Android

Included in Expo Go

Recommended version:

~57.0.22

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

Expo UI 提供五种按钮组件，它们与官方 Jetpack Compose Button API 相匹配：Button（实心），FilledTonalButton，OutlinedButton，ElevatedButton 和 TextButton。所有变体共享相同的属性，并接受可组合子作为内容。

🌐 Expo UI provides five button components that match the official Jetpack Compose Button API: Button (filled), FilledTonalButton, OutlinedButton, ElevatedButton, and TextButton. All variants share the same props and accept composable children for content.

Filled, outlined, and text buttons showing the Material 3 emphasis hierarchy

类型	外观	目的
实心	实色背景搭配对比文字。	用于高强调动作的按钮，比如“提交”和“保存”。
实心调色	背景颜色会根据表面进行变化。	也是用于主要或重要操作。实心调色按钮视觉重量更重，适用于“加入购物车”和“登录”等功能。
浮起	带有阴影，使其突出。	功能类似于调色按钮。提高浮起效果，可以让按钮更显眼。
描边	只有边框，没有填充。	中等强调的按钮，包含重要但非主要的操作。与其他按钮搭配，表示替代的次要操作，比如“取消”或“返回”。
文字	仅显示文字，没有背景或边框。	低强调按钮，适合不那么关键的操作，如导航链接或次要功能，比如“了解更多”或“查看详情”。

安装

🌐 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

基础按钮

🌐 Basic button

实心按钮是默认的、高强调的主要操作按钮。

🌐 A filled button is the default, high-emphasis button for primary actions.

BasicButtonExample.tsx

import { Host, Button, Text } from '@expo/ui/jetpack-compose';

export default function BasicButtonExample() {
  return (
    <Host matchContents>
      <Button onClick={() => alert('Pressed!')}>
        <Text>Press me</Text>
      </Button>
    </Host>
  );
}

按钮变体

🌐 Button variants

使用不同的按钮组件来传达不同程度的强调。

🌐 Use different button components to convey varying levels of emphasis.

ButtonVariantsExample.tsx

import {
  Host,
  Button,
  FilledTonalButton,
  OutlinedButton,
  ElevatedButton,
  TextButton,
  Column,
  Text,
} from '@expo/ui/jetpack-compose';

export default function ButtonVariantsExample() {
  return (
    <Host matchContents>
      <Column verticalArrangement={{ spacedBy: 8 }}>
        <Button onClick={() => {}}>
          <Text>Filled</Text>
        </Button>
        <FilledTonalButton onClick={() => {}}>
          <Text>Filled Tonal</Text>
        </FilledTonalButton>
        <OutlinedButton onClick={() => {}}>
          <Text>Outlined</Text>
        </OutlinedButton>
        <ElevatedButton onClick={() => {}}>
          <Text>Elevated</Text>
        </ElevatedButton>
        <TextButton onClick={() => {}}>
          <Text>Text</Text>
        </TextButton>
      </Column>
    </Host>
  );
}

带图标的按钮

🌐 Button with icons

由于按钮可以接受可组合的子元素，你可以使用 Icon 组件添加前置和后置图标。这遵循带图标的 Material 3 按钮模式（官方示例），使用 18dp 图标大小，图标与标签之间间距为 8dp。

🌐 Since buttons accept composable children, you can add leading and trailing icons using the Icon component. This follows the Material 3 buttons with icon pattern (official sample), use 18dp icon size, 8dp spacing between the icon and label.

ButtonWithIconsExample.tsx

import {
  Host,
  Button,
  OutlinedButton,
  FilledTonalButton,
  Column,
  Icon,
  Spacer,
  Text,
} from '@expo/ui/jetpack-compose';
import { width } from '@expo/ui/jetpack-compose/modifiers';

const addIcon = require('./assets/add.png');
const sendIcon = require('./assets/send.png');

export default function ButtonWithIconsExample() {
  return (
    <Host matchContents>
      <Column verticalArrangement={{ spacedBy: 8 }}>
        {/* Leading icon */}
        <Button onClick={() => {}}>
          <Icon source={addIcon} size={18} tint="#FFFFFF" />
          <Spacer modifiers={[width(8)]} />
          <Text>Add item</Text>
        </Button>

        {/* Trailing icon */}
        <OutlinedButton onClick={() => {}}>
          <Text>Send</Text>
          <Spacer modifiers={[width(8)]} />
          <Icon source={sendIcon} size={18} />
        </OutlinedButton>

        {/* Both leading and trailing icons */}
        <FilledTonalButton onClick={() => {}}>
          <Icon source={addIcon} size={18} />
          <Spacer modifiers={[width(8)]} />
          <Text>Create & Send</Text>
          <Spacer modifiers={[width(8)]} />
          <Icon source={sendIcon} size={18} />
        </FilledTonalButton>
      </Column>
    </Host>
  );
}

自定义颜色

🌐 Custom colors

使用 colors 属性覆盖容器和内容颜色。

🌐 Override container and content colors using the colors prop.

CustomColorsExample.tsx

import { Host, Button, Text } from '@expo/ui/jetpack-compose';

export default function CustomColorsExample() {
  return (
    <Host matchContents>
      <Button
        onClick={() => {}}
        colors={{
          containerColor: '#6200EE',
          contentColor: '#FFFFFF',
        }}>
        <Text>Purple Button</Text>
      </Button>
    </Host>
  );
}

自定义形状

🌐 Custom shape

CustomShapeExample.tsx

import {
  Host,
  Button,
  Shape,
  Text,
} from '@expo/ui/jetpack-compose';

export default function CustomShapeExample() {
  return (
    <Host matchContents>
      <Button
        onClick={() => {}}
        shape={Shape.RoundedCorner({
          cornerRadii: { topStart: 16, bottomEnd: 16 },
        })}>
        <Text>Custom Shape</Text>
      </Button>
    </Host>
  );
}

应用接口

🌐 API

import {
  Button,
  FilledTonalButton,
  OutlinedButton,
  ElevatedButton,
  TextButton,
} from '@expo/ui/jetpack-compose';

Components

`Button`

Android

Type: React.Element<ButtonProps>

A filled button component.

ButtonProps

`children`

Android

Type: ReactNode

Content to display inside the button.

`colors`

Android

Optional • Type: ButtonColors

Colors for button elements.

`contentPadding`

Android

Optional • Type: ButtonContentPadding

The padding between the button container and its content. Use this to adjust internal spacing, for example when adding a leading icon

`enabled`

Android

Optional • Type: boolean • Default: true

Whether the button is enabled for user interaction.

`modifiers`

Android

Optional • Type: ModifierConfig[]

Modifiers for the component.

`onClick`

Android

Optional • Type: () => void

Callback that is called when the button is clicked.

`shape`

Android

Optional • Type: ShapeJSXElement

The shape of the button.

`ElevatedButton`

Android

Type: React.Element<ButtonProps>

An elevated button component.

`FilledTonalButton`

Android

Type: React.Element<ButtonProps>

A filled tonal button component.

`OutlinedButton`

Android

Type: React.Element<ButtonProps>

An outlined button component.

`TextButton`

Android

Type: React.Element<ButtonProps>

A text button component.

Types

`ButtonColors`

Android

Colors for button elements.

Property	Type	Description
containerColor(optional)	`ColorValue`	-
contentColor(optional)	`ColorValue`	-
disabledContainerColor(optional)	`ColorValue`	-
disabledContentColor(optional)	`ColorValue`	-

`ButtonContentPadding`

Android

Content padding for the button's inner content. All values are in density-independent pixels (dp).

Property	Type	Description
bottom(optional)	`number`	-
end(optional)	`number`	-
start(optional)	`number`	-
top(optional)	`number`	-