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

按钮

一个用于显示原生按钮的 SwiftUI Button 组件。

iOS

tvOS

Included in Expo Go

GitHub

npm

更新日志

如需跨平台使用，请查看通用的 Button —— 它会根据平台渲染相应的原生组件。

Expo UI Button 与官方 SwiftUI Button API 一致，并支持通过 buttonStyle、controlSize 以及其他修饰器进行样式设置。

两个 iOS 26 Liquid Glass 按钮——上方是一个 glassProminent 的“开始使用”，下方是一个 glass 的“了解更多”

安装

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.

用法

基础按钮

BasicButtonExample.tsx

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

export default function BasicButtonExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Button label="Press me" onPress={() => alert('Pressed!')} />
    </Host>
  );
}

带系统图像的按钮

ButtonWithImageExample.tsx

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

export default function ButtonWithImageExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Button
        label="下载"
        systemImage="arrow.down.circle"
        onPress={() => alert('正在下载...')}
      />
    </Host>
  );
}

仅含图标的按钮

使用 labelStyle 修饰器在保留辅助功能标签的同时仅显示图标。

IconOnlyButtonExample.tsx

import { Host, Button } from '@expo/ui/swift-ui';
import { labelStyle } from '@expo/ui/swift-ui/modifiers';

export default function IconOnlyButtonExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Button
        label="设置"
        systemImage="gear"
        modifiers={[labelStyle('iconOnly')]}
        onPress={() => alert('设置')}
      />
    </Host>
  );
}

按钮样式

使用 buttonStyle 修饰器更改按钮外观。可用样式有：bordered、borderedProminent、borderless、plain、glass 和 glassProminent。

注意： glass 和 glassProminent 样式仅在使用 Xcode 26 构建时、iOS 26+ 上可用。

ButtonStylesExample.tsx

import { Host, Button, VStack } from '@expo/ui/swift-ui';
import { buttonStyle } from '@expo/ui/swift-ui/modifiers';

export default function ButtonStylesExample() {
  return (
    <Host style={{ flex: 1 }}>
      <VStack spacing={8}>
        <Button
          label="Bordered"
          modifiers={[buttonStyle('bordered')]}
        />
        <Button
          label="Bordered Prominent"
          modifiers={[buttonStyle('borderedProminent')]}
        />
        <Button
          label="Borderless"
          modifiers={[buttonStyle('borderless')]}
        />
        <Button label="Plain" modifiers={[buttonStyle('plain')]} />
      </VStack>
    </Host>
  );
}

按钮边框形状

使用 buttonBorderShape 修饰器更改样式化按钮的形状。可用形状有：automatic、capsule、roundedRectangle 和 circle（iOS 17+）。

ButtonBorderShapeExample.tsx

import { Host, Button } from '@expo/ui/swift-ui';
import {
  buttonStyle,
  controlSize,
  buttonBorderShape,
  labelStyle,
} from '@expo/ui/swift-ui/modifiers';

export default function ButtonBorderShapeExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Button
        label="Favorite"
        systemImage="heart.fill"
        modifiers={[
          buttonStyle('glass'),
          controlSize('extraLarge'),
          labelStyle('iconOnly'),
          buttonBorderShape('circle'),
        ]}
        onPress={() => alert('Favorited')}
      />
    </Host>
  );
}

控件尺寸

使用 controlSize 修饰器调整按钮大小。可用尺寸有：mini、small、regular、large 和 extraLarge。

注意： extraLarge 尺寸仅在 iOS 17+ 上可用。

ControlSizeExample.tsx

import { Host, Button, VStack } from '@expo/ui/swift-ui';
import {
  buttonStyle,
  controlSize,
} from '@expo/ui/swift-ui/modifiers';

export default function ControlSizeExample() {
  return (
    <Host style={{ flex: 1 }}>
      <VStack spacing={8}>
        <Button
          label="Mini"
          modifiers={[controlSize('mini'), buttonStyle('bordered')]}
        />
        <Button
          label="Small"
          modifiers={[
            controlSize('small'),
            buttonStyle('bordered'),
          ]}
        />
        <Button
          label="Regular"
          modifiers={[
            controlSize('regular'),
            buttonStyle('bordered'),
          ]}
        />
        <Button
          label="Large"
          modifiers={[
            controlSize('large'),
            buttonStyle('bordered'),
          ]}
        />
      </VStack>
    </Host>
  );
}

按钮角色

使用 role 属性指示按钮的语义角色。可用角色有：default、cancel 和 destructive。

ButtonRolesExample.tsx

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

export default function ButtonRolesExample() {
  return (
    <Host style={{ flex: 1 }}>
      <VStack spacing={8}>
        <Button label="默认" role="default" />
        <Button label="取消" role="cancel" />
        <Button label="删除" role="destructive" />
      </VStack>
    </Host>
  );
}

着色按钮

使用 tint 修饰器更改按钮颜色。

TintedButtonExample.tsx

import { Host, Button } from '@expo/ui/swift-ui';
import { tint } from '@expo/ui/swift-ui/modifiers';

export default function TintedButtonExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Button label="Custom Color" modifiers={[tint('#FF6347')]} />
    </Host>
  );
}

禁用按钮

使用 disabled 修饰器禁用按钮。

DisabledButtonExample.tsx

import { Host, Button } from '@expo/ui/swift-ui';
import { disabled } from '@expo/ui/swift-ui/modifiers';

export default function DisabledButtonExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Button label="Disabled" modifiers={[disabled()]} />
    </Host>
  );
}

自定义标签内容

你可以将自定义组件作为 children 传入，以实现更复杂的按钮标签内容。

CustomContentExample.tsx

import {
  Host,
  Button,
  VStack,
  Image,
  Text,
} from '@expo/ui/swift-ui';

export default function CustomContentExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Button onPress={() => console.log('Pressed!')}>
        <VStack spacing={4}>
          <Image systemName="folder" />
          <Text>文件夹</Text>
        </VStack>
      </Button>
    </Host>
  );
}

API

import { Button } from '@expo/ui/swift-ui';

Component

`Button`

iOS

tvOS

Type: React.Element<ButtonProps>

Displays a native button component.

Example

import { Button } from '@expo/ui/swift-ui';
import { buttonStyle, controlSize, tint, disabled } from '@expo/ui/swift-ui/modifiers';

<Button
  role="destructive"
  onPress={handlePress}
  label="Delete"
  modifiers={[
    buttonStyle('bordered'),
    controlSize('large'),
    tint('#FF0000'),
    disabled(true)
  ]}
/>

ButtonProps

`children`

iOS

tvOS

Optional • Literal type: union

Custom content for the button label. Use this for custom label views. Only nested elements are supported, not plain strings.

Acceptable values are: ReactElement<unknown, string | JSXElementConstructor<any>> | ReactElement[]

`label`

iOS

tvOS

Optional • Type: string

The text label for the button. Use this for simple text buttons.

`onPress`

iOS

tvOS

Optional • Type: () => void

A callback that is called when the button is pressed.

`role`

iOS

tvOS

Optional • Type: ButtonRole

Indicates the role of the button.

`systemImage`

iOS

tvOS

Optional • Type: SFSymbols7_0

A string describing the system image to display in the button. Only used when label is provided.

`target`

iOS

tvOS

Optional • Type: string

Target identifier for the button, used for identifying which button was pressed in widgets and live activities.

Inherited props

CommonViewModifierProps

Types

`ButtonRole`

iOS

tvOS

Literal type: string

The role of the button.

default - The default button role.
cancel - A button that cancels the current operation.
destructive - A button that deletes data or performs a destructive action.
close - A button that closes the view it is presented in. Given no label and no children, the system draws it as an xmark.

Acceptable values are: 'default' | 'cancel' | 'destructive' | 'close'