App Intents và Siri Shortcuts: tự động hóa iOS nâng cao 2026

import AppIntents

// Một AppIntent đại diện cho hành động mà người dùng có thể thực hiện
struct CreateTaskIntent: AppIntent {
    // Tiêu đề hiển thị trong Phím tắt và Siri
    static var title: LocalizedStringResource = "Tạo nhiệm vụ"

    // Mô tả cho khả năng truy cập và đề xuất
    static var description = IntentDescription(
        "Tạo nhiệm vụ mới trong ứng dụng."
    )

    // Tham số có xác thực tự động
    @Parameter(title: "Tiêu đề nhiệm vụ")
    var taskTitle: String

    // Tham số tùy chọn với giá trị mặc định
    @Parameter(title: "Mức độ ưu tiên", default: .medium)
    var priority: TaskPriority

    // Thực thi hành động
    func perform() async throws -> some IntentResult & ReturnsValue<TaskEntity> {
        // Tạo nhiệm vụ qua service
        let task = TaskService.shared.createTask(
            title: taskTitle,
            priority: priority
        )

        // Trả về entity đã tạo để chaining
        return .result(value: TaskEntity(task: task))
    }
}

import AppIntents

// Mô hình dữ liệu nội bộ
struct Task: Identifiable, Codable {
    let id: UUID
    var title: String
    var priority: TaskPriority
    var isCompleted: Bool
    var dueDate: Date?
}

// Entity được phơi bày cho hệ thống
struct TaskEntity: AppEntity {
    // Định danh duy nhất bắt buộc
    var id: UUID

    // Các thuộc tính có thể hiển thị
    var title: String
    var priority: TaskPriority
    var isCompleted: Bool

    // Cấu hình hiển thị trong hệ thống
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Nhiệm vụ"

    // Biểu diễn trực quan của instance
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(
            title: "\(title)",
            subtitle: "\(priority.rawValue)",
            image: .init(systemName: isCompleted ? "checkmark.circle.fill" : "circle")
        )
    }

    // Query mặc định để tìm kiếm entity
    static var defaultQuery = TaskEntityQuery()

    // Initializer từ mô hình nội bộ
    init(task: Task) {
        self.id = task.id
        self.title = task.title
        self.priority = task.priority
        self.isCompleted = task.isCompleted
    }
}

// Query để tìm kiếm và lọc entity
struct TaskEntityQuery: EntityQuery {
    // Tìm kiếm theo định danh
    func entities(for identifiers: [UUID]) async throws -> [TaskEntity] {
        TaskService.shared.fetchTasks()
            .filter { identifiers.contains($0.id) }
            .map { TaskEntity(task: $0) }
    }

    // Đề xuất hiển thị trong giao diện
    func suggestedEntities() async throws -> [TaskEntity] {
        TaskService.shared.fetchTasks()
            .filter { !$0.isCompleted }
            .prefix(5)
            .map { TaskEntity(task: $0) }
    }
}

import AppIntents

// Enum được phơi bày cho hệ thống
enum TaskPriority: String, AppEnum, Codable {
    case low
    case medium
    case high

    // Tên kiểu hiển thị
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Mức độ ưu tiên"

    // Biểu diễn từng trường hợp
    static var caseDisplayRepresentations: [TaskPriority: DisplayRepresentation] = [
        .low: DisplayRepresentation(
            title: "Thấp",
            image: .init(systemName: "arrow.down.circle")
        ),
        .medium: DisplayRepresentation(
            title: "Trung bình",
            image: .init(systemName: "minus.circle")
        ),
        .high: DisplayRepresentation(
            title: "Cao",
            image: .init(systemName: "exclamationmark.circle")
        )
    ]
}

// Enum cho trạng thái nhiệm vụ
enum TaskStatus: String, AppEnum, Codable {
    case pending
    case inProgress
    case completed

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Trạng thái"

    static var caseDisplayRepresentations: [TaskStatus: DisplayRepresentation] = [
        .pending: "Đang chờ",
        .inProgress: "Đang tiến hành",
        .completed: "Hoàn thành"
    ]
}

import AppIntents

// Provider khai báo tất cả phím tắt của ứng dụng
struct TaskAppShortcutsProvider: AppShortcutsProvider {
    // Tối đa 10 phím tắt mỗi ứng dụng
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        // Phím tắt để tạo nhiệm vụ
        AppShortcut(
            intent: CreateTaskIntent(),
            phrases: [
                // Placeholder .applicationName là BẮT BUỘC
                "Tạo nhiệm vụ với \(.applicationName)",
                "Nhiệm vụ mới trong \(.applicationName)",
                "Thêm nhiệm vụ vào \(.applicationName)"
            ],
            shortTitle: "Tạo nhiệm vụ",
            systemImageName: "plus.circle"
        )

        // Phím tắt để liệt kê nhiệm vụ
        AppShortcut(
            intent: ListTasksIntent(),
            phrases: [
                "Hiển thị nhiệm vụ của tôi trong \(.applicationName)",
                "Hiển thị nhiệm vụ từ \(.applicationName)",
                "Nhiệm vụ của tôi là gì \(.applicationName)"
            ],
            shortTitle: "Nhiệm vụ của tôi",
            systemImageName: "list.bullet"
        )

        // Phím tắt với tham số động
        AppShortcut(
            intent: CompleteTaskIntent(),
            phrases: [
                "Hoàn thành \(\.$taskName) trong \(.applicationName)",
                "Đánh dấu \(\.$taskName) là xong với \(.applicationName)"
            ],
            shortTitle: "Hoàn thành nhiệm vụ",
            systemImageName: "checkmark.circle"
        )
    }
}

import AppIntents

struct CompleteTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Hoàn thành nhiệm vụ"

    static var description = IntentDescription(
        "Đánh dấu nhiệm vụ là đã hoàn thành."
    )

    // Tham số entity với tìm kiếm tự động
    @Parameter(title: "Nhiệm vụ")
    var task: TaskEntity

    // Tham số tùy chọn với ngày
    @Parameter(title: "Ngày hoàn thành")
    var completionDate: Date?

    // Cấu hình hộp thoại Siri
    static var parameterSummary: some ParameterSummary {
        Summary("Hoàn thành \(\.$task)") {
            \.$completionDate
        }
    }

    func perform() async throws -> some IntentResult & ProvidesDialog {
        // Cập nhật nhiệm vụ
        TaskService.shared.completeTask(
            id: task.id,
            completionDate: completionDate ?? Date()
        )

        // Phản hồi giọng nói cho Siri
        return .result(
            dialog: "Nhiệm vụ \(task.title) đã được đánh dấu là hoàn thành."
        )
    }
}

// Intent trả về danh sách entity
struct ListTasksIntent: AppIntent {
    static var title: LocalizedStringResource = "Liệt kê nhiệm vụ"

    // Bộ lọc tùy chọn
    @Parameter(title: "Trạng thái", default: nil)
    var statusFilter: TaskStatus?

    @Parameter(title: "Mức độ ưu tiên", default: nil)
    var priorityFilter: TaskPriority?

    func perform() async throws -> some IntentResult & ReturnsValue<[TaskEntity]> {
        var tasks = TaskService.shared.fetchTasks()

        // Áp dụng bộ lọc
        if let status = statusFilter {
            tasks = tasks.filter {
                switch status {
                case .completed: return $0.isCompleted
                case .pending, .inProgress: return !$0.isCompleted
                }
            }
        }

        if let priority = priorityFilter {
            tasks = tasks.filter { $0.priority == priority }
        }

        let entities = tasks.map { TaskEntity(task: $0) }
        return .result(value: entities)
    }
}

import AppIntents

// Tuân thủ domain Bookmarks để tích hợp Apple Intelligence
struct SaveBookmarkIntent: AppIntent {
    static var title: LocalizedStringResource = "Lưu dấu trang"

    // Tham số URL với xác thực tự động
    @Parameter(title: "URL")
    var url: URL

    @Parameter(title: "Tiêu đề", default: nil)
    var title: String?

    @Parameter(title: "Thư mục", default: nil)
    var folder: BookmarkFolderEntity?

    // Mở ứng dụng nếu cần
    static var openAppWhenRun: Bool = false

    func perform() async throws -> some IntentResult & ProvidesDialog {
        let bookmark = BookmarkService.shared.save(
            url: url,
            title: title,
            folder: folder?.id
        )

        return .result(
            dialog: "Dấu trang đã lưu: \(bookmark.title)"
        )
    }
}

// Intent với khả năng nhận biết nội dung màn hình (iOS 18.4+)
struct AnalyzeScreenContentIntent: AppIntent {
    static var title: LocalizedStringResource = "Phân tích nội dung"

    // Truy cập ngữ cảnh màn hình qua Apple Intelligence
    @Parameter(title: "Ngữ cảnh")
    var screenContext: String?

    func perform() async throws -> some IntentResult & ProvidesDialog {
        guard let context = screenContext else {
            return .result(dialog: "Không có nội dung để phân tích.")
        }

        // Xử lý nội dung được Apple Intelligence trích xuất
        let analysis = ContentAnalyzer.analyze(context)

        return .result(dialog: analysis.summary)
    }
}

import AppIntents

struct DeleteTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Xóa nhiệm vụ"

    @Parameter(title: "Nhiệm vụ")
    var task: TaskEntity

    // Yêu cầu xác nhận của người dùng
    static var isDiscoverable: Bool = true

    func perform() async throws -> some IntentResult & ProvidesDialog {
        // Yêu cầu xác nhận qua hộp thoại
        try await requestConfirmation(
            result: .result(
                dialog: "Bạn có chắc muốn xóa \(task.title) không?"
            )
        )

        // Xóa sau khi xác nhận
        TaskService.shared.deleteTask(id: task.id)

        return .result(
            dialog: "Nhiệm vụ \(task.title) đã được xóa."
        )
    }
}

// Intent với nhiều bước hộp thoại
struct ScheduleTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Lập lịch nhiệm vụ"

    @Parameter(title: "Nhiệm vụ")
    var task: TaskEntity

    @Parameter(title: "Ngày")
    var scheduledDate: Date

    @Parameter(title: "Lời nhắc", default: true)
    var setReminder: Bool

    static var parameterSummary: some ParameterSummary {
        When(\.$setReminder, .equalTo, true) {
            Summary("Lập lịch \(\.$task) cho \(\.$scheduledDate) kèm lời nhắc")
        } otherwise: {
            Summary("Lập lịch \(\.$task) cho \(\.$scheduledDate)")
        }
    }

    func perform() async throws -> some IntentResult & ProvidesDialog {
        TaskService.shared.schedule(
            taskId: task.id,
            date: scheduledDate,
            reminder: setReminder
        )

        let dateFormatter = DateFormatter()
        dateFormatter.dateStyle = .medium
        dateFormatter.timeStyle = .short

        let formattedDate = dateFormatter.string(from: scheduledDate)

        return .result(
            dialog: "Nhiệm vụ đã được lập lịch cho \(formattedDate)."
        )
    }
}

import AppIntents
import WidgetKit

// Intent được tối ưu cho widget (thực thi nhanh)
struct ToggleTaskFromWidgetIntent: AppIntent {
    static var title: LocalizedStringResource = "Chuyển đổi nhiệm vụ"

    @Parameter(title: "ID nhiệm vụ")
    var taskID: String

    init() {}

    init(taskID: UUID) {
        self.taskID = taskID.uuidString
    }

    // Không hộp thoại cho widget
    func perform() async throws -> some IntentResult {
        guard let uuid = UUID(uuidString: taskID) else {
            return .result()
        }

        TaskService.shared.toggleCompletion(taskId: uuid)

        // Làm mới widget tức thì
        WidgetCenter.shared.reloadTimelines(ofKind: "TaskWidget")

        return .result()
    }
}

// View widget với nút tương tác
import SwiftUI

struct TaskWidgetView: View {
    let task: Task

    var body: some View {
        Button(intent: ToggleTaskFromWidgetIntent(taskID: task.id)) {
            HStack {
                Image(systemName: task.isCompleted ? "checkmark.circle.fill" : "circle")
                    .foregroundStyle(task.isCompleted ? .green : .secondary)

                Text(task.title)
                    .strikethrough(task.isCompleted)
            }
            .padding()
        }
        .buttonStyle(.plain)
    }
}

import AppIntents

// Intent được tối ưu cho Action Button
struct QuickCaptureIntent: AppIntent {
    static var title: LocalizedStringResource = "Ghi nhận nhanh"

    static var description = IntentDescription(
        "Tạo nhanh nhiệm vụ với tiêu đề."
    )

    // Mở ứng dụng để nhập
    static var openAppWhenRun: Bool = true

    func perform() async throws -> some IntentResult & OpensIntent {
        // Thông báo để mở màn hình ghi nhận nhanh
        NotificationCenter.default.post(
            name: .quickCaptureTriggered,
            object: nil
        )

        return .result(opensIntent: ShowQuickCaptureViewIntent())
    }
}

// Khai báo trong AppShortcutsProvider cho Action Button
extension TaskAppShortcutsProvider {
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        // ... các phím tắt khác

        AppShortcut(
            intent: QuickCaptureIntent(),
            phrases: [
                "Ghi nhận nhanh \(.applicationName)",
                "Ghi chú nhanh \(.applicationName)"
            ],
            shortTitle: "Ghi nhận",
            systemImageName: "bolt.circle"
        )
    }
}

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "TaskIntents",
    platforms: [
        .iOS(.v17),
        .macOS(.v14),
        .watchOS(.v10)
    ],
    products: [
        .library(name: "TaskIntents", targets: ["TaskIntents"])
    ],
    dependencies: [],
    targets: [
        .target(
            name: "TaskIntents",
            dependencies: []
        )
    ]
)

// Sources/TaskIntents/SharedIntents.swift
import AppIntents

// Intent dùng chung đa nền tảng
public struct SharedCreateTaskIntent: AppIntent {
    public static var title: LocalizedStringResource = "Tạo nhiệm vụ"

    @Parameter(title: "Tiêu đề")
    public var taskTitle: String

    public init() {}

    public func perform() async throws -> some IntentResult {
        // Logic dùng chung
        await TaskRepository.shared.create(title: taskTitle)
        return .result()
    }
}

// Mở rộng dành riêng cho nền tảng trong ứng dụng
#if os(iOS)
extension SharedCreateTaskIntent {
    // Hành vi đặc thù iOS
    static var openAppWhenRun: Bool = false
}
#endif

import XCTest
import AppIntents
@testable import TaskApp

final class TaskIntentTests: XCTestCase {

    override func setUp() {
        super.setUp()
        // Đặt lại service cho các test cô lập
        TaskService.shared.reset()
    }

    func testCreateTaskIntent() async throws {
        // Given
        var intent = CreateTaskIntent()
        intent.taskTitle = "Nhiệm vụ kiểm thử"
        intent.priority = .high

        // When
        let result = try await intent.perform()

        // Then
        let tasks = TaskService.shared.fetchTasks()
        XCTAssertEqual(tasks.count, 1)
        XCTAssertEqual(tasks.first?.title, "Nhiệm vụ kiểm thử")
        XCTAssertEqual(tasks.first?.priority, .high)
    }

    func testCompleteTaskIntent() async throws {
        // Given
        let task = TaskService.shared.createTask(
            title: "Nhiệm vụ cần hoàn thành",
            priority: .medium
        )

        var intent = CompleteTaskIntent()
        intent.task = TaskEntity(task: task)

        // When
        _ = try await intent.perform()

        // Then
        let updatedTask = TaskService.shared.fetchTask(id: task.id)
        XCTAssertTrue(updatedTask?.isCompleted ?? false)
    }

    func testEntityQuery() async throws {
        // Given
        let task1 = TaskService.shared.createTask(title: "Nhiệm vụ 1", priority: .low)
        let task2 = TaskService.shared.createTask(title: "Nhiệm vụ 2", priority: .high)

        let query = TaskEntityQuery()

        // When
        let entities = try await query.entities(for: [task1.id, task2.id])

        // Then
        XCTAssertEqual(entities.count, 2)
    }
}

import AppIntents

// 1. Cụm từ được bản địa hóa
struct LocalizedTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "task.create.title"

    static var description = IntentDescription(
        "task.create.description",
        categoryName: "task.category"
    )

    @Parameter(title: "task.parameter.title")
    var taskTitle: String

    func perform() async throws -> some IntentResult {
        // ...
        return .result()
    }
}

// 2. Xử lý lỗi đúng cách
enum TaskIntentError: Error, CustomLocalizedStringResourceConvertible {
    case taskNotFound
    case invalidInput
    case serviceUnavailable

    var localizedStringResource: LocalizedStringResource {
        switch self {
        case .taskNotFound:
            return "Không tìm thấy nhiệm vụ."
        case .invalidInput:
            return "Dữ liệu không hợp lệ."
        case .serviceUnavailable:
            return "Dịch vụ tạm thời không khả dụng."
        }
    }
}

struct RobustTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Intent vững chắc"

    @Parameter(title: "ID")
    var taskId: String

    func perform() async throws -> some IntentResult & ProvidesDialog {
        guard let uuid = UUID(uuidString: taskId) else {
            throw TaskIntentError.invalidInput
        }

        guard let task = TaskService.shared.fetchTask(id: uuid) else {
            throw TaskIntentError.taskNotFound
        }

        return .result(dialog: "Đã tìm thấy nhiệm vụ: \(task.title)")
    }
}

// 3. Tối ưu EntityQuery
struct OptimizedTaskQuery: EntityStringQuery {
    // Tìm kiếm văn bản được tối ưu
    func entities(matching string: String) async throws -> [TaskEntity] {
        // Tìm kiếm phía service có giới hạn
        TaskService.shared.search(query: string, limit: 10)
            .map { TaskEntity(task: $0) }
    }

    // Đề xuất giới hạn để tối ưu hiệu năng
    func suggestedEntities() async throws -> [TaskEntity] {
        TaskService.shared.fetchRecentTasks(limit: 5)
            .map { TaskEntity(task: $0) }
    }
}

// 4. Focus Filter cho chế độ Tập trung
struct TaskFocusFilter: SetFocusFilterIntent {
    static var title: LocalizedStringResource = "Lọc nhiệm vụ"

    @Parameter(title: "Chỉ hiển thị ưu tiên cao")
    var showHighPriorityOnly: Bool

    func perform() async throws -> some IntentResult {
        TaskService.shared.setFocusFilter(highPriorityOnly: showHighPriorityOnly)
        return .result()
    }
}