iOS Widget 开发-12：Widget 深度链接与导航

Widget 虽然不能直接展示完整的 App 界面，但通过深度链接（Deep Link）和 URL 机制，可以实现从 Widget 精准跳转到 App 内部特定页面的功能，提升用户体验的连贯性。

本篇将讲解 Widget 中所有可用的跳转方式及其实现细节。

---

1. Widget 跳转方式概览

方式	引入版本	说明
.widgetURL(_:)	iOS 14	整Widget 唯一的点击目标，不支持多点
Link(destination:)	iOS 14	支持多个区域各有独立的跳转链接
Button(intent:) + openAppWhenRun	iOS 17	Intent 中返回 .opensAppWhenRun，执行后打开 App

---

2. widgetURL - 整Widget 单链接

最简单的跳转方式，整个 Widget 点击后跳转到同一个 URL：

struct MyWidgetView: View {
    var entry: MyEntry

    var body: some View {
        VStack {
            Text("今日天气")
            Text(entry.temperature)
        }
        .widgetURL(URL(string: "myapp://weather"))
    }
}

在主 App 中接收 URL

// App 入口（SwiftUI App）
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    handleDeepLink(url)
                }
        }
    }

    func handleDeepLink(_ url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return }
        let path = components.host

        switch path {
        case "weather":
            // 导航到天气页面
            navigateToWeather()
        case "todo":
            // 导航到待办页面
            navigateToTodo()
        default:
            break
        }
    }
}

注意：.widgetURL() 应用于整个 Widget 视图的根容器。一个 Widget 只能有一个 widgetURL。

---

3. Link - 多区域独立跳转

Link 允许在 Widget 的不同区域设置不同的跳转目标：

struct MultiLinkWidgetView: View {
    var entry: TodoEntry

    var body: some View {
        VStack(spacing: 0) {
            // 区域 1：点击跳转到待办列表
            Link(destination: URL(string: "myapp://todos")!) {
                HStack {
                    Image(systemName: "checklist")
                    Text("全部待办 (\(entry.totalCount))")
                        .font(.headline)
                }
                .frame(maxWidth: .infinity, alignment: .leading)
                .padding(.horizontal)
            }

            Divider()

            // 区域 2：点击跳转到具体待办
            ForEach(entry.todos.prefix(3)) { todo in
                Link(destination: URL(string: "myapp://todo/\(todo.id)")!) {
                    HStack {
                        Image(systemName: todo.isDone ? "checkmark.circle.fill" : "circle")
                        Text(todo.title)
                            .font(.caption)
                            .lineLimit(1)
                    }
                    .padding(.horizontal, 8)
                    .padding(.vertical, 4)
                }
            }
        }
    }
}

Link vs widgetURL 对比

特性	.widgetURL()	Link
跳转目标个数	1 个	多个（不限）
作用范围	整个 Widget	单个区域
优先级	低	高（Link 会覆盖 widgetURL）
适用场景	简单跳转、内容单一	内容列表、多入口

规则：如果 Widget 同时使用了 Link 和 .widgetURL()，则 Link 区域点击时使用 Link 的 URL，非 Link 区域点击时使用 .widgetURL() 的 URL。

---

4. Button(intent:) + openAppWhenRun

iOS 17+ 中，Button(intent:) 也可以在执行业务逻辑后打开 App：

struct OpenDetailIntent: AppIntent {
    static var title: LocalizedStringResource = "查看详情"
    static var openAppWhenRun: Bool = true

    @Parameter(title: "项目ID")
    var itemID: String

    func perform() async throws -> some IntentResult {
        // 可以通过共享容器传递上下文，让 App 启动时知道要导航到哪里
        let defaults = UserDefaults(suiteName: "group.com.example.app")
        defaults?.set(itemID, forKey: "pending_deeplink_id")

        return .result()
    }
}

// View 中使用
Button(intent: OpenDetailIntent(itemID: "123")) {
    Text("查看详情")
}

---

5. 系统尺寸下的小屏适配

systemSmall 空间有限，只适合放一个跳转入口：

struct SmallWidgetView: View {
    var entry: Entry

    var body: some View {
        Link(destination: URL(string: "myapp://main")!) {
            VStack {
                Image(systemName: getIcon(for: entry.type))
                    .font(.title)
                Text(entry.title)
                    .font(.caption)
                Text(entry.value)
                    .font(.headline)
            }
        }
    }
}

systemMedium 和 systemLarge 可以容纳多个 Link，实现更丰富的导航结构。

---

6. 主 App 侧的完整导航处理

class DeepLinkManager: ObservableObject {
    static let shared = DeepLinkManager()

    @Published var targetRoute: AppRoute?

    func handle(url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
              let host = components.host else { return }

        // 解析路径
        let pathItems = components.path.split(separator: "/").map(String.init)

        switch host {
        case "todo":
            if let todoID = pathItems.first {
                targetRoute = .todoDetail(id: todoID)
            } else {
                targetRoute = .todoList
            }

        case "weather":
            targetRoute = .weather

        case "settings":
            targetRoute = .settings

        default:
            targetRoute = .home
        }
    }
}

enum AppRoute {
    case home
    case todoList
    case todoDetail(id: String)
    case weather
    case settings
}

// 在 App 入口使用
struct MyApp: App {
    @StateObject private var deepLinkManager = DeepLinkManager.shared

    var body: some Scene {
        WindowGroup {
            RootView()
                .environmentObject(deepLinkManager)
                .onOpenURL { url in
                    deepLinkManager.handle(url: url)
                }
        }
    }
}

---

7. 常见问题

Q：Widget 中可以放多个 widgetURL 吗？

A：不能。一个 Widget 视图中只能应用一个 .widgetURL()。如果需要多个跳转目标，请使用 Link。

Q：Link 和 Button(intent:) 能共存吗？

A：可以共存。Link 负责跳转，Button(intent:) 负责操作。但如果 Button 嵌套在 Link 内部，Button 会拦截点击事件（同 UIKit 的 Hit Testing 层级规则）。

Q：点击 Widget 后如何回到主屏幕？

A：无法直接在 Widget 中实现。用户点击 Widget 后必然打开 App。如果不需要打开 App，考虑使用 Button(intent:) 而不设置 openAppWhenRun。

Q：长按 Widget 菜单中的操作和 Link 有什么区别？

A：长按菜单（contextMenu）是 iOS 17+ 的新功能，可以提供额外的快捷操作入口（通过 WidgetConfiguration.supportsContextMenuInteraction()），但与 Link 和 widgetURL 是独立的交互方式。

---

小结

• 简单场景用 widgetURL，复杂多入口用 Link
• 配合 App 侧的 Deep Link 系统实现精准导航
• iOS 17+ 的 Button(intent:) + openAppWhenRun 可实现"操作后跳转"的复合流程
• 使用 UserDefaults（App Group）传递跳转上下文，让 App 启动后知道应该导航到哪个页面

---

上一篇 ：iOS Widget 开发-11：Widget 交互按钮实战（iOS 17+ App Intents）