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

按钮

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

Android

GitHub

npm

更新日志

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

类型	外观	用途
填充	实心背景，文本具有对比色。	高强调按钮，用于“提交”和“保存”等主要操作。
填充色调	背景颜色会变化以匹配表面。	也用于主要或重要操作。填充色调按钮具有更强的视觉权重，适合“加入购物车”和“登录”等功能。
提升	通过阴影突出显示。	与色调按钮用途相似。提高海拔值可让按钮显得更加醒目。
描边	带边框且无填充。	中等强调按钮，包含重要但非主要的操作。它们与其他按钮搭配良好，可用于表示“取消”或“返回”等替代性、次要操作。
文本	仅显示文本，没有背景或边框。	低强调按钮，适用于不太关键的操作，例如导航链接，或“了解更多”或“查看详情”等次要功能。

安装

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} tintColor="#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 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>紫色按钮</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: React.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`	-