SwiftUI核心组件详解

一、Text组件 - 文本显示

基础用法

Text("Hello, SwiftUI!")

字体样式

文本装饰

排版与布局

多样式文本

Text("混合格式: ")
    + Text("加粗").bold()
    + Text(" + ")
    + Text("彩色").foregroundColor(.blue)
    + Text(" + ")
    + Text("大号").font(.title)

二、Image组件 - 图片显示

使用SF Symbols

Image(systemName: "star.fill")
    .font(.largeTitle)
    .foregroundColor(.yellow)

自定义图片

Image("my-image")
    .resizable()
    .aspectRatio(contentMode: .fit)
    .frame(width: 100, height: 100)

图片效果

Image(systemName: "sun.max")
    .symbolRenderingMode(.hierarchical)
    .foregroundStyle(
        LinearGradient(
            colors: [.yellow, .orange],
            startPoint: .top,
            endPoint: .bottom
        )
    )

尺寸与缩放

外观效果

SF Symbols 专用属性

三、Button组件 - 按钮交互

基础按钮

Button("点击我") {
    print("按钮被点击")
}

带图标的按钮

// 写法1
Button(action: {
    // 点击处理
}) {
    Label("添加", systemImage: "plus")
}
// 写法2（苹果官方示例统一用这个）
Button{
    // 点击处理
 } label: {
    Label("添加", systemImage: "plus")
}

提示： Label 是独立组件，不只能放在 Button 中使用，也可以单独作为内容展示：

Label("设置", systemImage: "gear")  // 直接使用

自定义样式

Button {
    //点击事件
} label: {
    HStack(spacing: 12) {
        Image(systemName: "cart")
        VStack(alignment: .leading) {
            Text("立即下单")
                .font(.title3.bold())
        }
    }
    .padding()
    .frame(maxWidth: .infinity)
    .background(.orange)
    .foregroundColor(.white)
    .cornerRadius(12)
}
                

按钮样式

项目大量复用按钮时，自定义样式统一管理，不用重复写 padding、圆角

struct BlueButtonStyle: ButtonStyle {
    func makeBody(configuration: Configuration) -> some View {
        configuration.label
            .padding()
            .background(configuration.isPressed ? Color.blue.opacity(0.7) : Color.blue)
            .foregroundColor(.white)
            .cornerRadius(10)
            .scaleEffect(configuration.isPressed ? 0.96 : 1) // 按下缩小动画
    }
}

// 使用
Button {
    print("点击")
} label: {
    Text("自定义蓝色按钮")
}
.buttonStyle(BlueButtonStyle())

常用属性

按钮状态

带角色的 Button：ButtonRole

iOS 15+ 新增，区分按钮语义，系统自动适配颜色 / 弹窗逻辑
可选角色：

• .cancel 取消
• .destructive 删除、危险操作（自动红色）
• .confirm 确认
• .close 关闭

// 危险删除按钮
            Button(role: .destructive) {
                //删除事件
            } label: {
                HStack {
                    Image(systemName: "trash")
                    Text("清空计数")
                }
            }
            .buttonStyle(.borderedProminent)

四、TextField组件 - 文本输入

基础用法

@State private var text = ""

TextField("请输入文本", text: $text)
    .textFieldStyle(.roundedBorder)

自定义键盘类型

TextField("邮箱", text: $email)
    .keyboardType(.emailAddress)
    .textInputAutocapitalization(.never)  // iOS 15+ 推荐写法

搜索框

HStack {
    Image(systemName: "magnifyingglass")
        .foregroundColor(.secondary)
    TextField("搜索...", text: $searchText)
}
.padding()
.background(Color.gray.opacity(0.1))
.cornerRadius(10)

键盘配置

输入框样式

事件监听

五、SecureField组件 - 密码输入

基础用法

@State private var password = ""

SecureField("密码", text: $password)
    .textFieldStyle(.roundedBorder)

带显示/隐藏切换

@State private var isSecure = true

HStack {
    if isSecure {
        SecureField("密码", text: $password)
    } else {
        TextField("密码", text: $password)
    }
    
    Button(action: { isSecure.toggle() }) {
        Image(systemName: isSecure ? "eye.slash" : "eye")
    }
}
.textFieldStyle(.roundedBorder)

键盘配置

输入框样式

事件监听

六、Toggle组件 - 开关控制

基础开关

@State private var isOn = false

Toggle("开启功能", isOn: $isOn)

自定义样式

Toggle(isOn: $darkMode) {
    HStack {
        Image(systemName: "moon.fill")
        Text("深色模式")
    }
}
.toggleStyle(SwitchToggleStyle(tint: .purple))

按钮样式开关

Toggle(isOn: $isEnabled) {
    Text("启用通知")
}
.toggleStyle(.button)

开关样式

常用属性

七、Slider组件 - 滑块选择

基础滑块

@State private var value = 0.5

Slider(value: $value, in: 0...1)

带范围和步进

Slider(
    value: $temperature,
    in: -10...40,
    step: 1
) {
    Text("温度")
}

带标签滑块

VStack {
    Text("亮度: \(Int(brightness * 100))%")
    Slider(value: $brightness, in: 0...1)
        .tint(.yellow)
}

初始化参数

常用属性

八、Stepper组件 - 步进控制

基础步进器

@State private var count = 0

Stepper("数量: \(count)", value: $count)

自定义范围

Stepper(
    "音量: \(Int(volume * 100))%",
    value: $volume,
    in: 0...1,
    step: 0.1
)

带图标步进器

Stepper(value: $quantity, in: 0...99) {
    HStack {
        Image(systemName: "cart")
        Text("数量: \(quantity)")
    }
}

初始化参数

常用属性

九、Picker组件 - 选择器

基础选择器

@State private var selectedOption = "A"

Picker("选项", selection: $selectedOption) {
    Text("选项 A").tag("A")
    Text("选项 B").tag("B")
    Text("选项 C").tag("C")
}
.pickerStyle(.segmented)

菜单样式

Picker("选择语言", selection: $language) {
    Text("Swift").tag("swift")
    Text("Python").tag("python")
    Text("JavaScript").tag("js")
}
.pickerStyle(.menu)

滚轮样式

Picker("选择日期", selection: $day) {
    ForEach(days, id: \.self) { day in
        Text(day).tag(day)
    }
}
.pickerStyle(.wheel)

选择器样式

常用属性

注意： Picker 的选中绑定是直接写在初始化器中，没有 .selection(_:) 这个 modifier。

十、DatePicker组件 - 日期选择

基础用法

@State private var selectedDate = Date()

DatePicker("选择日期", selection: $selectedDate)

日期范围

DatePicker(
    "选择日期",
    selection: $selectedDate,
    in: Date()...,
    displayedComponents: .date
)

时间选择

DatePicker(
    "选择时间",
    selection: $selectedDate,
    displayedComponents: [.date, .hourAndMinute]
)

初始化参数

日期选择器样式

显示组件类型

常用属性

十一、ColorPicker组件 - 颜色选择

基础用法

@State private var selectedColor = Color.blue

ColorPicker("选择颜色", selection: $selectedColor)

带透明度

ColorPicker("选择颜色", selection: $selectedColor, supportsOpacity: true)

初始化参数

常用属性

十二、ProgressView组件 - 进度显示

基础进度条

ProgressView(value: progress) {
    Text("加载中...")
}

圆形进度

ProgressView()
    .progressViewStyle(.circular)

自定义样式

ProgressView(value: progress)
    .progressViewStyle(LinearProgressViewStyle(tint: .blue))

初始化参数

进度条样式

常用属性

十三、List组件 - 列表展示

基础列表

List {
    Text("第一项")
    Text("第二项")
    Text("第三项")
}

使用ForEach

let items = ["苹果", "香蕉", "橙子"]

List(items, id: \.self) { item in
    Text(item)
}

分组列表

List {
    Section("水果") {
        Text("苹果")
        Text("香蕉")
    }
    
    Section("蔬菜") {
        Text("胡萝卜")
        Text("西兰花")
    }
}

可选择列表

struct SelectableList: View {
    let items = ["选项1", "选项2", "选项3"]
    @State private var selectedItem: String?
    
    var body: some View {
        // 方式1：点击选中（常用）
        List {
            ForEach(items, id: \.self) { item in
                Text(item)
                    .onTapGesture {
                        selectedItem = item
                    }
                    .background(selectedItem == item ? Color.accentColor.opacity(0.2) : Color.clear)
            }
        }
    }
}

// 方式2：编辑模式选中（selection 参数仅在编辑模式生效）
struct EditModeList: View {
    let items = ["选项1", "选项2", "选项3"]
    @State private var selectedItem: String?
    @Environment(\.editMode) private var editMode
    
    var body: some View {
        List(items, id: \.self, selection: $selectedItem) { item in
            Text(item)
        }
        .toolbar {
            EditButton()  // 需要编辑按钮才能启用 selection
        }
    }
}

重要提示： List 的 selection 参数只在编辑模式（EditButton）下生效，不是普通的点击选中。普通点击选中需要使用 .onTapGesture。

列表样式

行配置属性

分组配置属性

常用属性

注意： List 的 selection 参数是直接写在初始化器中（List(selection: $selected)），且只在编辑模式（EditButton）下生效。普通点击选中请使用 .onTapGesture。

十四、Form组件 - 表单布局

基础表单

Form {
    Section {
        TextField("用户名", text: $username)
        SecureField("密码", text: $password)
    }
    
    Section {
        Toggle("记住我", isOn: $rememberMe)
    }
    
    Section {
        Button("登录") {
            // 登录逻辑
        }
    }
}

表单控件组合

Form {
    Section {
        TextField("姓名", text: $name)
        TextField("邮箱", text: $email)
            .keyboardType(.emailAddress)
        DatePicker("出生日期", selection: $birthDate)
    }
    
    Section {
        Slider(value: $volume, in: 0...1) {
            Text("音量")
        }
        
        Stepper("数量: \(quantity)", value: $quantity, in: 1...10)
    }
}

表单样式

常用属性

Section 属性

十五、NavigationStack - 导航容器

基础导航

NavigationStack {
    List(items) { item in
        NavigationLink(value: item) {
            Text(item.name)
        }
    }
    .navigationDestination(for: Item.self) { item in
        DetailView(item: item)
    }
    .navigationTitle("标题")
}

导航栏样式

NavigationStack {
    // 内容
}
.navigationBarTitleDisplayMode(.large)   // 大标题
.navigationBarTitleDisplayMode(.inline) // 行内标题

工具栏

NavigationStack {
    List { ... }
    .toolbar {
        ToolbarItem(placement: .navigationBarLeading) {
            Button("返回") { }
        }
        ToolbarItem(placement: .navigationBarTrailing) {
            Button("保存") { }
        }
    }
}

标题配置

导航目标

注意： .navigationBarItems(leading:trailing:) 已在 iOS 15+ 废弃，统一使用 .toolbar 替代。

工具栏配置

十六、TabView - 标签页视图

基础标签页

TabView {
    HomeView()
        .tabItem {
            Image(systemName: "house")
            Text("首页")
        }
    
    SearchView()
        .tabItem {
            Image(systemName: "magnifyingglass")
            Text("搜索")
        }
    
    ProfileView()
        .tabItem {
            Image(systemName: "person")
            Text("我的")
        }
}

带选中状态

TabView(selection: $selectedTab) {
    HomeView()
        .tabItem {
            Image(systemName: "house")
            Text("首页")
        }
        .tag(0)
    
    SearchView()
        .tabItem {
            Image(systemName: "magnifyingglass")
            Text("搜索")
        }
        .tag(1)
}

TabView样式

常用属性

注意： TabView 的选中绑定是直接写在初始化器中（TabView(selection: $selectedTab)），没有 .selection(_:) 这个 modifier。

TabItem 配置

十七、布局组件

VStack - 垂直布局

VStack(alignment: .leading, spacing: 8) {
    Text("第一行")
    Text("第二行")
    Text("第三行")
}

HStack - 水平布局

HStack(alignment: .center, spacing: 12) {
    Image(systemName: "star")
    Text("评分")
    Spacer()
    Text("5.0")
}

ZStack - 层叠布局

ZStack {
    Circle()
        .fill(Color.blue)
        .frame(width: 100, height: 100)
    
    Image(systemName: "checkmark")
        .foregroundColor(.white)
        .font(.title)
}

Spacer - 空白填充

HStack {
    Text("左对齐")
    Spacer()  // 占据中间所有空间
    Text("右对齐")
}

Divider - 分隔线

VStack {
    Text("上方内容")
    Divider()
    Text("下方内容")
}

VStack 属性

HStack 属性

ZStack 属性

LazyVStack & LazyHStack

核心特性：懒加载

• 屏幕外的视图不会被创建，只有滚动到可见区域时才会创建
• 滚动性能更高，适合大量数据列表
• LazyVStack 垂直懒加载，LazyHStack 水平懒加载

// 示例：高效展示大量数据
ScrollView {
    LazyVStack {
        ForEach(0..<1000) { index in
            Text("项目 \(index)")
                .frame(height: 50)
        }
    }
}

Spacer 属性

Divider 属性

十八、自定义组件

创建可复用组件

struct FeatureCard: View {
    let icon: String
    let title: String
    let description: String
    
    var body: some View {
        VStack(spacing: 8) {
            Image(systemName: icon)
                .font(.title)
                .foregroundColor(.blue)
            
            Text(title)
                .font(.headline)
            
            Text(description)
                .font(.caption)
                .foregroundColor(.secondary)
        }
        .padding()
        .background(Color.gray.opacity(0.1))
        .cornerRadius(12)
    }
}

// 使用
FeatureCard(
    icon: "star",
    title: "功能标题",
    description: "功能描述"
)

使用@ViewBuilder自定义容器

struct CardContainer<Content: View>: View {
    let content: Content
    
    init(@ViewBuilder content: () -> Content) {
        self.content = content()
    }
    
    var body: some View {
        VStack {
            content
        }
        .padding()
        .background(Color.white)
        .cornerRadius(16)
        .shadow(radius: 4)
    }
}

// 使用
CardContainer {
    Text("卡片内容")
    Button("点击") { }
}

十九、组件组合示例

完整表单示例

struct LoginView: View {
    @State private var email = ""
    @State private var password = ""
    @State private var rememberMe = false
    
    var body: some View {
        VStack(spacing: 20) {
            Image(systemName: "person.circle")
                .font(.system(size: 64))
                .foregroundColor(.blue)
            
            TextField("邮箱", text: $email)
                .textFieldStyle(.roundedBorder)
            
            SecureField("密码", text: $password)
                .textFieldStyle(.roundedBorder)
            
            Toggle(isOn: $rememberMe) {
                Text("记住我")
            }
            
            Button("登录") {
                // 登录逻辑
            }
            .buttonStyle(.borderedProminent)
            .tint(.blue)
        }
        .padding()
    }
}

完整列表示例

struct ContactRow: View {
    let contact: Contact
    
    var body: some View {
        HStack(spacing: 12) {
            Image(systemName: "person.circle")
                .font(.title)
            
            VStack(alignment: .leading, spacing: 4) {
                Text(contact.name)
                    .font(.headline)
                Text(contact.phone)
                    .font(.caption)
                    .foregroundColor(.secondary)
            }
            
            Spacer()
            
            Image(systemName: "chevron.right")
                .foregroundColor(.secondary)
        }
    }
}

二十、Alert组件 - 警告弹窗

基础用法

@State private var showAlert = false

Button("显示警告") {
    showAlert = true
}
.alert("提示", isPresented: $showAlert) {
    Button("确定", role: .cancel) { }
}

带多个按钮

.alert("确认删除", isPresented: $showAlert) {
    Button("取消", role: .cancel) { }
    Button("删除", role: .destructive) {
        // 执行删除
    }
} message: {
    Text("此操作不可撤销")
}

Alert 属性

按钮角色

二十一、Sheet组件 - 模态表单

基础用法

@State private var showSheet = false

Button("打开详情") {
    showSheet = true
}
.sheet(isPresented: $showSheet) {
    DetailView()
}

带数据传递

@State private var selectedItem: Item?

.sheet(item: $selectedItem) { item in
    DetailView(item: item)
}

Sheet 属性

高度模式

二十二、Shape组件 - 图形绘制

Circle - 圆形

Circle()
    .fill(Color.blue)
    .frame(width: 100, height: 100)

Rectangle - 矩形

Rectangle()
    .fill(Color.red)
    .frame(width: 200, height: 100)

RoundedRectangle - 圆角矩形

RoundedRectangle(cornerRadius: 16)
    .fill(Color.green)
    .frame(width: 200, height: 100)

Ellipse - 椭圆

Ellipse()
    .fill(Color.purple)
    .frame(width: 150, height: 80)

Capsule - 胶囊形状

Capsule()
    .fill(Color.orange)
    .frame(width: 100, height: 40)

Shape 常用属性

Path - 自定义路径

Path { path in
    path.move(to: CGPoint(x: 10, y: 10))
    path.addLine(to: CGPoint(x: 100, y: 10))
    path.addLine(to: CGPoint(x: 100, y: 100))
    path.closeSubpath()
}
.stroke(Color.blue, lineWidth: 2)

二十三、动画组件 - 动画效果

withAnimation - 显式动画

Button("动画") {
    withAnimation(.spring()) {
        isExpanded.toggle()
    }
}

animation - 隐式动画

Circle()
    .frame(width: isLarge ? 100 : 50)
    .animation(.easeInOut, value: isLarge)

动画类型

重要提示： iOS 15+ 推荐使用带 value 参数的 .animation()，避免诡异的动画效果。

弹簧动画参数

transition - 过渡动画

if showView {
    Text("Hello")
        .transition(.slide)
}

过渡类型

matchedGeometryEffect - 共享元素过渡

@Namespace private var namespace

// 源视图
Image("photo")
    .matchedGeometryEffect(id: "photo", in: namespace)

// 目标视图
Image("photo")
    .matchedGeometryEffect(id: "photo", in: namespace)