我想用SwiftUI打造一個運動軌跡App，該從哪裡開始？

說到把HealthKit裡面那些運動紀錄變成地圖上的色彩軌跡，好像有種把音樂的節奏直接灑在螢幕上的感覺。有時候，一段跑步數據忽然被渲染成紅通通的一條線，會讓人想起搖滾樂剛起來的那股衝勁。其實以前在Nike待過一陣子，那時就常常跟這些健康資料打交道，試圖做出讓人感覺活生生的功能。不過今天要聊的，就是怎麼用SwiftUI寫個小App，把走路、慢跑畫到地圖上，隨便加個起點終點標記，看起來應該還不差。走路大致上就是一條綠色線，不會太突兀；如果是慢跑，大概會比較熱情，整條路徑呈現紅色。有些人可能覺得這沒什麼，但換個角度，視覺化以後好像更容易回味自己那些日子的努力。

不過話說回來，每次真的要開始做之前，都還是得先開Xcode弄專案設定。雖然這步驟挺無趣，有點像彈吉他前得花幾分鐘調音，但多半也就一下下吧——搞定了之後才有機會玩真的。有些細節，大約七八成都差不多，但每次新建專案總感覺哪裡又不太一樣。不知道是不是只有我這樣？反正備妥環境對後面流程通常滿有幫助，省掉不少麻煩。

有時候在開啟 Xcode 那個時候，大家大概會直接點到左上角那幾個選單，像是「檔案」底下有個什麼「新建」然後又有一堆類型。通常選那種標註 iOS 的 App 模板，反正現在也沒有人還特別去找那些太舊的東西。下一步？嗯，取名字嘛——RouteMapper 或是其他想得到比較順眼、聽起來不錯的名稱都可以。像使用者介面這邊，大部份看起來現在都偏向 SwiftUI，那語言就用 Swift 嘛。版本的話，大致設定在最近一兩代內吧，比如說 iOS 十七左右，畢竟大家多半也會習慣更新啦。

然後按幾下下一步、決定要把它丟在哪裡，按建立之後，其實專案就算活過來了。整體流程很直觀，也沒什麼複雜細節，大概只花不到幾分鐘。

不過事情還沒完全結束。假設你想跟 HealthKit 有點關聯——這部分倒是不能跳過，不然資料進不來，就白做工了。在左側那個專案瀏覽器區，你應該能看到自己的專案名在最上面。有些人一開始還找不到在哪兒，但其實仔細看就在眼前。切到簽署與功能那一頁，有個加號功能，看起來應該就是加一些權限或特殊能力的地方。

搜尋欄敲進 HealthKit，那清單就會跳出相關東西。選它，然後再確認加入。有沒有啟用成功，有時候界面會給個提示，不過大致上只要照著步驟做都行得通。至於之後怎麼跟 HealthKit 溝通，那又是另外一回事了——至少目前已經算把門打開了，不見得每一步都需要死記，只要大方向抓住差不多就好。

有時候，HealthKit 對於隱私這件事特別講究，說起來也可以理解，畢竟牽涉到個人健康資料。假如有人想讓 App 跟 HealthKit 聊一聊，好像得先交代清楚用意才行。有些人操作的步驟大致上是這樣：從左邊那一排找到專案（其實很容易迷路），然後點進去選個目標（Target），接著 Info 這個分頁就在簽署設定旁邊，也不算難找。滑下去會看到一段什麼自訂屬性，大概類似「Custom iOS Target Properties」之類的名稱吧。那邊有個加號，其實點了以後應該能選到「Privacy - Health Share Usage Description」這種描述，英文名字大致是 NSHealthShareUsageDescription。

至於填寫內容，有人會寫得很客氣，例如說：「我們會用您的健康資料來顯示運動路線地圖。」像這種句子，看起來就比較好理解，HealthKit 可能也比較願意給通行證。

事情大致上就是這麼回事啦。如果想跟 HealthKit 多互動幾句，好像不能太直接闖進去，要先禮貌地打聲招呼。差不多得有點像在音樂會要進後台那種感覺，不是每個人都能隨便過門檻的。實際申請授權，大約就是整個流程的第一步吧。

健康資料這玩意兒，不會隨便就攤給你。要想摸到裡頭的東西，首先得先過一個「問好」的關卡。沒那個授權，你的 App 大概連彈奏都算不上，就像拿了把沒裝弦的吉他，按再多和弦也只剩空氣聲。

流程其實有點繁瑣，差不多要在 Xcode 裡面，某個簽名或能力那邊加進 HealthKit 的權限。有些人還會補上一份大致說明用戶資料用途的政策，好像是蘋果特別在意這種事情。然後程式碼部分，也不是亂寫一通——有些開發者喜歡弄個 actor，把操作包起來。一來感覺比較整潔，再來就是異步、非同步那些執行緒問題多少能簡單一點。async/await 這種語法，好像最近變得蠻普及。

舉個例子，有人會這樣設計：弄一個 HealthKitManager，大致上裡面藏著 healthStore 這麼一個東西。至於授權申請，大概意思是去跟系統講一下：「想讀取幾種運動記錄還有路線資訊可以嗎？」型態什麼的也沒太仔細，只是挑了幾樣最常見。不過實際呼叫時，還要等系統回應才知道結果。有時候可能順利，有時候又不知道哪裡卡住——出錯時就把錯誤丟出去，沒事就繼續跑流程。

順序嘛，其實很多人寫法不太一樣。有些細節可能每家都不同，比如權限對話框跳出時間點，有時早有時晚。不過核心思想大概就是如此，要拿到資料前，都得先經歷這些零零總總的大約三四步吧。如果少了其中一步，很容易什麼都撈不到。

如果有在碰健康資料這塊，最近有人會把 HealthKitManager 這一塊單獨拉出來做個 actor，主要是因為安全性嘛，畢竟現在多執行緒情境變得比以前還常見。這種寫法，其實也不算罕見，但好像也不是每個人都會在意。不過說到重點，大概就是它會管那些 HealthKit 的操作，把權限請求、存取什麼的集中起來處理。

這邊要注意的授權範圍，不外乎兩大類：運動紀錄資料（他們叫 workoutType），還有路線資訊（workoutRoute）。通常前者比較廣泛，涵蓋整體活動狀況；而後者就專注於 GPS 位置那邊。有些人說，雖然不少應用只關心其中一項，但一起申請好像更省事。

其實蘋果之前那套 callback 寫法，用久了應該都覺得有點煩吧。現在大家慢慢轉用 async/await，那個程式碼乾淨很多，看起來也沒那麼繞。大致上就是你可以在 App 一啟動時，就先丟 requestAuthorization() 去跑——感覺很直觀，不需要一直被回呼卡住流程。

程式細節嘛……其實差不多，就是幾步檢查，有成功、有失敗，也可能遇到例外錯誤。最後授權過沒過，都會給個回傳結果。嚴格講裡面用了 withCheckedThrowingContinuation 這招，好像有人說這樣比較保險？但到底是不是每次都要那麼小心，有時候看需求啦。

總之，如果想試著把健康資料相關的東西包裝一下，其實大致架構就長這樣。有些地方或許還能再調整，要不要加功能、怎麼管理狀態，好像沒有哪種一定更好，只能說目前看到的大約是朝這方向發展……

步驟二：這裡大概就是把那些步行跟跑步的運動資料抓下來。你會發現每種運動到時候在地圖上都會有自己的顏色，視覺效果多少有點趣味（有人可能特別愛這種小細節）。然後，像下面這段 Swift 程式碼，就是在處理怎麼從 HealthKit 把資料撈出來：

extension HealthKitManager {

    func fetchWorkouts() async throws -> [HKWorkout] {

        let predicate = HKQuery.predicateForWorkouts(with: [.walking, .running])

        let sortDescriptor = NSSortDescriptor(key: HKSampleSortIdentifierEndDate, ascending: false)

        

        return try await withCheckedThrowingContinuation { continuation in

            let query = HKSampleQuery(

                sampleType: .workoutType(),

                predicate: predicate,

                limit: 0,

                sortDescriptors: [sortDescriptor]

            )

            healthStore.execute(query) { _, samples, error in

                if let error = error {

                    continuation.resume(throwing: error)

                } else if let workouts = samples as? [HKWorkout] {

                    continuation.resume(returning: workouts)

                }

            }

        }

    }

}

其實做的事情沒那麼複雜。首先，用那個 predicateForWorkouts 就只挑出走路還有跑步的活動，其他什麼瑜珈、伸展之類基本都不會進來。如果你不想回頭看到好幾年前的資料佔滿清單，也不用擔心——因為排序方式是從最近到比較久以前，基本滑個幾下大多數人就能找到自己想看的東西了。

HealthKit 本身是用 callback，那一串 withCheckedThrowingContinuation 看起來有點繞，但主要就是讓你可以用 async/await 去寫非同步程式，比較順手。這邊如果有什麼錯誤發生，大致也會被拋出去，不太容易漏掉。

下一個步驟嘛，就是要把這些資料真的放到地圖上。有些人也許只關心怎麼讓不同運動看起來顏色不一樣，有的人則可能很在意開始和結束的位置是不是有標記。不過這裡先暫停一下，後面再說。

有時候，App 的生命力大概就是從這裡開始浮現的。你會發現，HealthKitManager 裡面那個 fetchRoute 方法，其實就是在嘗試把一場運動的軌跡撈出來。它繞了點路，先抓到可能只有幾筆甚至更少的路徑資料，再去用 HKWorkoutRouteQuery 把 GPS 點一個一個拉回來。那些 CLLocation 物件，好像也不是每次都很乖巧，但多半能順利轉成地圖上用的座標。

其實流程沒有想像中複雜──只要找到運動紀錄，就能想辦法把該段路線還原出來。如果哪次沒有撈到資料，也許是記錄本身就沒存或者有其他原因，不一定是系統問題。

等這些步驟都過了，顯示在地圖上才真的是關鍵。有些人會選 SwiftUI 的 Map，那看起來乾淨直接，還能畫上一條線路、加起點跟終點的標記。那個「返回」按鈕，有時候擺著比較安心，用戶可以隨時跳回前一頁。

如果仔細觀察那段 SwiftUI code，其實裡面藏了一些小巧思。Map 上面的折線（Polyline），顏色會依照運動型態變化，比如跑步就紅色、走路則偏綠。至於標註嘛，開頭通常是一顆綠旗或藍色大頭針，尾巴可能換成藍色圓圈，也有人喜歡反過來。不過這種小細節也不太影響整體感覺。

地圖中心點，大致就以第一個座標作為參考，如果真的要更精確，也許得算一下所有點的平均值，不過多數情況下這樣設定已經夠用了。有的人會希望地圖自動縮放，把整條路線都包進去，但有時懶得調整也無妨。

仔細說起來，每一步好像都不是特別難，可是串起來之後，那份互動感和真實性才慢慢浮現。有些功能其實只用到少數幾行程式碼，但調整細節卻花上不少時間。而且遇到 HealthKit 有時傳回空資料，也不能完全預期下一次還會不會發生。雖然如此，大部分使用者倒是很容易被這種視覺化結果吸引住目光——即使只是簡單的一條線，配上兩個符號和顏色差異，看起來也挺有意思的。

總之，每當畫面終於把自己剛剛走過或跑過的軌跡勾勒出來，那種滿足感，大概只有親身碰過才懂。不見得每次都是完美呈現，有時某些細節被省略或者顏色沒對齊，不過在多數情境下，已經足以讓人暫時忽略背後的小瑕疵。

在設定區域中心和跨度時，其實就是大致抓個範圍，會用到那些最大、最小的緯度經度。然後上頭左邊還有個「返回」按鈕，看起來像個膠囊形狀，純粹是讓人能很快回上一頁。

進入點比較隨性，是靠初始化那段把地圖的初始區域設成第一筆路徑資料的位置。不過如果沒什麼座標，那也只能弄個空白的地圖區塊頂著。

說到整合，把所有零碎功能串一起，這才算是主畫面吧。其實這一頁主要就是列出從健康資料裡撈出來的運動記錄，讓人選了之後，再跳到地圖看路線。想像一下，有點像拼圖最後要補上的那片——全靠這裡做連結。

畫面裡用了導航視圖，列表則是一排排列出那些運動，不論跑步還是散步，只要按下就會去載對應的路線資料。然後再用彈窗方式把地圖顯示出來。至於授權流程，差不多一開始就會問健康資料權限，如果沒通過，也不是直接卡住，就是丟條訊息提醒你失敗；如果順利拿到，就慢慢從健康資料拉出各種訓練紀錄給你看。

雖然程式碼看起來規矩，但細節上其實不太死板，比如數據量級大概就是七八筆，有時甚至不到五筆記錄，全得看手機裡到底存了多少東西。有時候操作下去可能會發現某次運動找不到路徑，那系統也只會小聲提示一下，不至於影響整體使用體驗啦。

講真，用戶互動和流程安排還算簡單易懂——先授權、再抓資料、最後顯示內容。只是偶爾遇到異常或沒數據時，介面也不會太生硬，大致維持一種自然過渡的感覺。如果真要挑毛病，大概就是清單項目只有跑步跟走路這兩類型，有些其他活動目前好像還沒考慮進來。不過以現階段需求來說，也已經夠用了。

打開那個應用程式，好像一開始就會問你要不要給它健康數據的授權。有人說這種授權畫面其實不太容易拒絕，反正大多數人最後還是會同意吧。等你按下去後，大概沒多久，就會出現一串運動紀錄，排列得也不是特別規律，有時候順序還怪怪的。每個運動旁邊是一個可以點的按鈕，看起來像清單那樣，但不是很花俏。

有些人習慣點進其中一項，比方說在機場散步那種活動，只要輕輕碰一下，它就會去找跟這次運動相關的一條路線資料。當然啦，不是每次都能馬上拿到結果，有時候網路慢一點、或者資料本身就怪怪的，也常發生。系統如果抓不到那些軌跡點，反而會跳出訊息提醒你「好像沒有座標耶」，不至於讓人什麼都看不到卻又毫無頭緒。

偶爾遇到載入地圖頁面，視窗則是浮在上層，用類似對話框的方式出現，你自己決定要不要關掉再回主畫面。有些細節，比如選擇哪種運動型態、或是哪條路線，其實都是用傳遞參數的方式丟進去那張地圖頁裡頭。但說真的，如果剛好碰上讀取錯誤，那錯誤訊息倒也算直接顯示在螢幕上，不太藏著掖著。

整體感覺嘛——大致就是如此：流程沒複雜到難懂，只是偶爾小狀況還不少。不過對部分使用者來講，能夠先被提醒「這趟旅程沒有軌跡」之類的小事，好像比忽然什麼都沒反應要友善一些。

這一頁面其實就像個總匯，零零散散地把那些從HealthKit撈出來的資訊變成可以摸得著、看得見的畫面。現在大家大概能瞧見自己的運動記錄，順便把路線再回味一下，說不定還挺有意思。🎉

想到最後嘛——這個App也許只是個起點，對於想要研究HealthKit到底能做什麼的人來說，也算是某種程度上的入門磚吧。裡頭那堆運動數據，加上地圖線條的視覺感，都還有不少空間可以慢慢加東西進去，比如說加入高低起伏的圖啊、步速變化線什麼的……誰知道呢？搞不好哪天你會想讓這些路線像演唱會安可一樣閃亮登場。🎸

如果有人正好在找原生行動開發相關內容，可以偶爾逛逛[https://medium.com/@wesleymatlock](/@wesleymatlock) ——我自己寫的一些文章都放那邊了，大致上涵蓋不少面向。不管怎樣，有興趣的話多試試、多玩玩也無妨，也許哪天你走在路上，就突然想到了新花樣。🚶 反正路還長嘛！🏃‍♂️