This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

按钮

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

Android

Included in Expo Go

GitHub

npm

更新日志

有关跨平台用法，请参见通用的 Button —— 它会针对每个平台渲染相应的原生组件。

Expo UI 提供了五个按钮组件，与官方 Jetpack Compose Button API 保持一致：Button（填充）、FilledTonalButton、OutlinedButton、ElevatedButton 和 TextButton。所有变体都共享相同的 props，并接受可组合子元素作为内容。

类型	外观	用途
Filled	实心背景，搭配对比鲜明的文本。	用于“提交”和“保存”等主要操作的高强调按钮。
Filled tonal	背景颜色会变化以匹配表面颜色。	同样用于主要或重要的操作。填充色调按钮具有更强的视觉重量，适合“添加到购物车”和“登录”等功能。
Elevated	通过阴影使按钮更加突出。	用途与色调按钮类似。提高高度可使按钮显得更加突出。
Outlined	带有边框但没有填充。	中等强调按钮，用于包含重要但非主要的操作。它们与其他按钮搭配良好，用于表示“取消”或“返回”等替代性次要操作。
Text	仅显示文本，没有背景或边框。	低强调按钮，适合导航链接等不太重要的操作，或“了解更多”“查看详情”等次要功能。

安装

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.

用法

基础按钮

填充按钮是用于主要操作的默认高强调按钮。

BasicButtonExample.tsx

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

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

按钮变体

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

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>填充</Text>
        </Button>
        <FilledTonalButton onClick={() => {}}>
          <Text>填充色调</Text>
        </FilledTonalButton>
        <OutlinedButton onClick={() => {}}>
          <Text>描边</Text>
        </OutlinedButton>
        <ElevatedButton onClick={() => {}}>
          <Text>提升</Text>
        </ElevatedButton>
        <TextButton onClick={() => {}}>
          <Text>文本</Text>
        </TextButton>
      </Column>
    </Host>
  );
}

带图标的按钮

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

ButtonWithIconsExample.tsx

import {
  Host,
  Button,
  OutlinedButton,
  FilledTonalButton,
  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>
      {/* 前置图标 */}
      <Button onClick={() => {}}>
        <Icon source={addIcon} size={18} tint="#FFFFFF" />
        <Spacer modifiers={[width(8)]} />
        <Text>添加项目</Text>
      </Button>

      {/* 后置图标 */}
      <OutlinedButton onClick={() => {}}>
        <Text>发送</Text>
        <Spacer modifiers={[width(8)]} />
        <Icon source={sendIcon} size={18} />
      </OutlinedButton>

      {/* 同时包含前置和后置图标 */}
      <FilledTonalButton onClick={() => {}}>
        <Icon source={addIcon} size={18} />
        <Spacer modifiers={[width(8)]} />
        <Text>创建并发送</Text>
        <Spacer modifiers={[width(8)]} />
        <Icon source={sendIcon} size={18} />
      </FilledTonalButton>
    </Host>
  );
}

自定义颜色

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

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>紫色按钮</Text>
      </Button>
    </Host>
  );
}

自定义形状

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>自定义形状</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`	-