按钮

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

iOS

tvOS

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~58.0.1

信息如需跨平台使用，请参阅通用 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="Download"
        systemImage="arrow.down.circle"
        onPress={() => alert('Downloading...')}
      />
    </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="Settings"
        systemImage="gear"
        modifiers={[labelStyle('iconOnly')]}
        onPress={() => alert('Settings')}
      />
    </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="Default" role="default" />
        <Button label="Cancel" role="cancel" />
        <Button label="Delete" 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>Folder</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'