Button

创建基础按钮

文本按钮

使用 init(_:action:) 初始化方法创建 Button，该方法的2种定义如下：

 1/// 创建按钮
 2/// - Parameters:
 3///     - titleKey: 按钮本地化标题的键，用于描述按钮操作的目的。
 4///     - action: 用户触发按钮时要执行的操作。
 5@preconcurrency nonisolated
 6init( 
 7    _ titleKey: LocalizedStringKey,
 8    action: @escaping @MainActor () -> Void
 9)
10
11/// 创建按钮
12/// - Parameters:
13///     - title: 描述按钮操作目的的字符串。
14///     - action: 用户触发按钮时要执行的操作。
15@preconcurrency nonisolated
16init<S>(
17    _ title: S,
18    action: @escaping @MainActor () -> Void
19) where S : StringProtocol

示例：

1Button("按钮") {
2    btnAction()
3}
4
5private func btnAction(){ ... }

自定义按钮

使用 init(action:label:) 创建一个显示自定义标签的按钮。该方法的定义如下：

1/// 创建一个显示自定义标签的按钮
2/// - Parameters:
3///     - action: 用户触发按钮时要执行的操作。
4///     - label: 描述按钮操作目的的视图。
5@preconcurrency
6init(
7    action: @escaping @MainActor () -> Void,
8    @ViewBuilder label: () -> Label
9)

示例：

1Button(action: btnAction) {
2    Text("按钮")
3}
4private func btnAction(){ ... }

系统图标按钮

使用 init(_:systemImage:action:) 创建一个显示系统图标的按钮。该方法的2种定义如下：

 1/// 创建一个显示系统图标和文字标签的按钮
 2/// - Parameters:
 3///     - titleKey: 按钮本地化标题的键，用于描述按钮操作的目的。
 4///     - systemImage: 系统图标名称。
 5///     - action: 用户触发按钮时要执行的操作。
 6nonisolated
 7init(
 8    _ titleKey: LocalizedStringKey,
 9    systemImage: String,
10    action: @escaping @MainActor () -> Void
11)
12
13/// 创建一个显示系统图标和文字标签的按钮
14/// - Parameters:
15///     - title: 描述按钮操作目的的字符串。
16///     - systemImage: 系统图标名称。
17///     - action: 用户触发按钮时要执行的操作。
18nonisolated
19init<S>(
20    _ title: S,
21    systemImage: String,
22    action: @escaping @MainActor () -> Void
23) where S : StringProtocol

示例：

1Button("按钮", systemImage: "plus") {
2    btnAction()
3}
4    
5private func btnAction(){ ... }

创建角色按钮

ButtonRole 结构体描述了按钮的用途，用于调整按钮的外观和行为。系统提供以下角色类型：

№	角色	说明	效果
0	destructive	执行破坏性操作（如删除数据）	红色样式
1	cancel	取消当前操作	特殊样式（平台相关）
2	plain	普通按钮（iOS 15+）	无特殊效果

文本角色按钮

使用 init(_:role:action:) 初始化方法：

1Button("删除", role: .destructive) {
2    deleteAction()
3}

系统图标角色按钮

使用 init(_:systemImage:role:action:) 初始化方法：

1Button("删除", systemImage: "trash", role: .destructive) {
2    deleteAction()
3}

Note

图标在左侧、文本在右侧展示。若文本为空字符串，则只展示图标；若系统图标名称错误，则只展示文本。

按钮的修饰符

ButtonStyle

实例方法 buttonStyle(_:) 接收一个符合 ButtonStyle 或 PrimitiveButtonStyle 协议的样式，为视图中的所有按钮设置统一的外观。

系统提供以下内置样式：

№	样式	说明	平台支持
0	automatic	默认样式，由系统自动决定	iOS 13+
1	bordered	带边框的按钮	iOS 13+
2	plain	文本样式的按钮	iOS 13+
3	borderless	无边框样式的按钮	iOS 13+
4	borderedProminent	背景突出样式的按钮	iOS 15+
5	glass	Liquid Glass 按钮	iOS 26+
6	glassProminent	Liquid Glass 突出效果按钮	iOS 26+
7	link	超链接样式	macOS 10.15+

 1/// 应用到单个按钮
 2Button("提交") {
 3    submitAction()
 4}
 5.buttonStyle(.borderedProminent)
 6
 7/// 应用到容器（所有子按钮生效）
 8HStack {
 9    Button("按钮1") { }
10    Button("按钮2") { }
11}
12.buttonStyle(.bordered)

buttonBorderShape

实例方法：buttonBorderShape(_:)。该方法接收一个 ButtonBorderShape 结构体值，用于设置按钮的边框形状。注意：此修饰符仅影响使用 bordered 或 borderedProminent 样式的按钮。

ButtonBorderShape 提供了以下形状选项：

№	形状	说明	平台支持
0	automatic	默认值，由系统根据上下文和平台自动决定合适的形状	iOS 15+
1	capsule	胶囊形状（药丸形）	iOS 15+
2	circle	圆形	iOS 17+
3	roundedRectangle	圆角矩形（默认圆角半径）	iOS 15+
4	roundedRectangle(radius:)	自定义圆角半径的圆角矩形	iOS 15+

 1/// 应用到单个按钮
 2Button("按钮") { }
 3    .buttonStyle(.bordered)
 4    .buttonBorderShape(.capsule)
 5
 6/// 应用到多个按钮
 7HStack {
 8    Button("按钮1") { }
 9    Button("按钮2") { }
10}
11.buttonStyle(.borderedProminent)
12.buttonBorderShape(.roundedRectangle(radius: 20))

平台支持

№	平台	最低版本
0	iOS	13.0+
1	iPadOS	13.0+
2	Mac Catalyst	13.0+
3	macOS	10.15+
4	tvOS	13.0+
5	watchOS	6.0+
6	visionOS	1.0+