Discover more from 13 報

13 的 Apple/iOS 開發者電子報

Over 2,000 subscribers

SwiftUI 專欄

SwiftUI 專欄 #6 文件工具與網站

SwiftUI 讀完就入坑 2022/09/07

Sep 6, 2022

13 的話

SwiftUI 專欄是一個教你入坑 SwiftUI 的付費專欄。不過我沒有設立付費牆，而是採用「誠實訂閱」制度。
希望可以累積到 100 位 Patreon 支持者，目前進度來到 27%，感謝新舊朋友們的支持。
如果你是第一次讀這個專欄，建議先回到目錄，照順序閱讀。
這期介紹了一些我有在使用的 SwiftUI 文件工具與網站，可以說是教你釣魚。
請記得看到最後，有我心目中的「最佳解」喔。
（看前一期 · 回專欄目錄 · 回首頁）

好的文件，對於學習一套程式框架是不可或缺的。而要這些查詢文件，就需要有適當的工具。

對我來說，使用 SwiftUI 文件工具，不出這三個目的：

查詢如何使用某個功能
瀏覽有哪些 SwiftUI API 是我還不知道的
分享特定 API 的資訊給其他人

以下工具與網站，我會分享使用的經驗，以及有沒有符合我的目的。如果喜歡的話，還請訂閱支持！

Apple 官網

網址：https://developer.apple.com/documentation/swiftui

Apple 官方文件在過去常常被詬病，有些新的 API 完全沒文件，只寫了一句「No overview available.」。甚至還有開發者專門架設 nooverviewavailable.com（已關站）調侃此事。SwiftUI 早期的文件也是很貧乏，許多功能都不知道怎麼使用。

但最近幾年 Apple 在 SwiftUI 文件下了苦工，很多元件甚至提供了截圖。

今年 Apple 官網的文件還做了一次改版，變成左邊有個目錄。跟 Xcode 內建的文件瀏覽器越來越像。

雖然內容看起來很豐富，但是好不好找資料呢？

簡單判斷 SwiftUI 文件查詢能力的方式，就是輸入「Text」，看看會找到什麼。畢竟這是一個很常見的元件，而且有許多使用方式。

很遺憾的是，輸入「Text」之後會找到成千上萬的 init function。看看這無敵長的捲軸，完全不實用嘛。

沒關係，我們可以從 Google 找😂

官網文件最大的好處就是有標準的網址，用瀏覽器就可以閱讀。適合分享。

所以，即使內建搜尋功能等於沒有，如果找得到特定 API 的頁面，還是會成為我認定的「權威文件」。

官網的文件也一定會包含 Beta 版，甚至還有 API Changes 的選單可以切換顯示。對於想知道最新變化的人來說，有一定的幫助。

Xcode 內建文件瀏覽器

打開 Xcode 以後，從 Window 選單找到「Developer Documentation」就是了。或是按 Cmd + Shift + 0。

就我個人的習慣來說，從 Xcode 看 SwiftUI 文件，不是很實用。原因是：

必須要開啟 Xcode 才能看。
文件版本綁定目前的 Xcode 版本。換言之，正式版 Xcode 看不到 Beta SwiftUI 的 API。

不過，至少它的搜尋功能比官網實用多了。

輸入「Text」以後可以看到 Text。

此外，從分享按鈕也可以複製對應的官網網址。

SwiftOnTap

網址：

https://swiftontap.com/

SwiftOnTap 是我過去最喜愛的 SwiftUI 文件網站。

它的優點很明顯：

提供相當不錯的搜尋功能
分類索引一目了然，可以很清楚知道有哪些 API
有提供截圖範例。這比 Apple 官方文件早了一、兩年就做到

但是它有很明顯的缺點，所以我現在無法推薦給大家：

由社群維護，準確性跟更新程度有問題。iOS 15 以後的資訊基本上都不在裡面
不知道什麼時候會關站。幾個月前，維護者在首頁聲明：如果沒有捐款支持的話，預計今年 8/31 會關閉（時間已過）。我不清楚為何每月「僅有」40,000 人次的網站需要 $400 美金才能繼續提供服務。

其實，讓我最困擾的還是該網站維護者的態度。

沒有積極維護這點我可以接受，畢竟這是件吃力不討好的事。但是沒有在首頁聲明文件的版本或更新資訊，以至於我用了很久才發現裡面根本沒有 iOS 15 的 API。我相信該網站的上萬使用者中，也有不少人跟我一樣落入這樣的坑。

MacBuka’s SwiftUI Index

網址：https://mackuba.eu/swiftui/changelog

這個網頁是開發者 Kuba Suder 在今年建立的。

特色是把 SwiftUI API 依照推出的版本（年份）排列，建立成索引。對於了解最新 API 有哪些，或是查詢向下相容非常方便。

每個項目點下去都是連到官網。可以說是官網索引的加強版。

Kuba 甚至整理到各 Beta 版的差異。像是 iOS 16 Beta 3 就推出了一堆新的、WWDC 沒提到的 API。Beta 2 與 4 也有少量新增，更別說 Beta 1 的大量 API。非常推薦各位去翻一下。

網站是在一頁裡面列出所有的 type、modifier、property wrapper、environment key 等等，所以可以用瀏覽器的全文搜尋，也可以用它提供的搜尋框。不過輸入「Text」仍然會找到一堆不相干的東西。

你也可以照主題分類來瀏覽。對於想把 SwiftUI 全部功能或是關鍵字都看過一遍的人來說，我覺得是很不錯的網站。

不過 Kuba 是否會妥善維護，還是會像 SwiftOnTap 那樣，明年 SwiftUI 更新時得留意一下。

SwiftUI Companion

The SwiftUI Lab 這個網站推出的 A Companion for SwiftUI app 是個要價 $50 美金或 $1690 新台幣的文件應用程式。在 Mac App Store 上評分很高。

我是用各位付費讀者的訂閱費用購買的，在此特別感謝支持🙏

但是作為文件工具的話，我不覺得好用，跟我的需求不符合。

首先，它很難查詢資料。輸入「Text」的效果比 Apple 官網好不到哪裡去。

其次，它的內容完全取自於 SwiftUI Lab 研究 SwiftUI 的教學文章，而不是抄自官網。編排、敘述、範例程式碼，都是自成一格。所以是輔助學習，而非「權威文件」。

有這樣的輔助學習教材並不是壞事。問題是，它沒有打開對應官網頁面的功能（不清楚原因，可能是怕 Apple 不給上架 Mac App Store？），所以我如果要比較兩邊的寫法，得自己用其他方式打開官方文件。

最後就會變成：既然我最後還是要看官方文件，那我就懶得開 Companion 了。

Companion 是很厲害的 SwiftUI 研究結晶，裡面有很多範例程式碼，以及從與官方不同的角度來解釋 API 的說明，甚至還有一鍵打開 Playground 檔案的功能。

對於學習 SwiftUI 來說，或許是個不錯的教材。其內容也完全對得起價格。

但是如果要當作文件工具來用的話，以我的標準是不合格的。當休閒書來讀、了解 API 的功能，倒是不錯。

如果能增加連結到官網的功能，就太好了。

Dash

官網：https://kapeli.com/dash

Dash 是知名的 Mac 文件工具，支援超過 200 種文件，當然也包括 Apple 的開發者文件。

作為 SwiftUI 文件工具，我覺得 Dash 相當好用，也是我平時最優先會選擇的工具。

首先，它的文件庫是從 Xcode 來的，而且支援 Beta 版。只要下載新的 Xcode，Dash 裡的文件庫就可以更新。在查詢時，就不需要開啟特定版本 Xcode。這點比 Xcode 內建的文件瀏覽器方便不少。

而且，由於文件庫是從 Xcode 來，所以你可以離線查詢。這點是勝過官網或者我提到的其他文件工具。

當然，這也表示它的文件索引就跟官方的一樣，不像 SwiftOnTap 或 MacBuka 那樣有用心編排過。至少我個人覺得，想要全面了解 SwiftUI API 的話，官方的索引不如前兩者。

Dash 有個小缺點，是 Apple 官方文件有時候會放截圖，這個目前在 Dash 是看不到的。幸好，Dash 跟官方文件的連動機制做得很好，可以從選單或快速鍵打開 Xcode 或是官網。

我常常在分享連結，很常用到「Copy Online Page URL」。

不過，Dash 目前的版本沒辦法只搜尋 SwiftUI 文件，而是會針對所有 Apple 文件。搜尋結果看得到是從哪個 framework 來的，但不能事先過濾掉。

對於只想看全部 SwiftUI API 的人來說，可能還是 MacBuka 的 Index 比較實際。

關於這點，我給 Dash 開發者提了意見，他之後可能會加進去唷。

Kapeli @kapeli

@ethanhuang13 @buildthatapp That's a great idea. I'm thinking of supporting the creation of a subset of a docset, given a parent docset and some filters. So you'd create a SwiftUI subset docset and then use it like all the other docsets in Dash.

最後重點，為何我會優先使用 Dash 呢？因為它有跟 Raycast 整合！

以前我都是 Alfred 作為快速進入 Google 搜尋的入口。所以找文件可能就是輸入「SwiftUI Text」之類關鍵字，然後再從 Google 搜尋結果進到 Apple 官網。

自從用了 Raycast + Dash 以後，就可以很輕鬆且快速的離線查詢了。

Dash 的售價是 $29.99 美金買斷，有試用期。我覺得非常超值，而且絕不是只能作為 SwiftUI 文件工具而已。

也是用各位付費讀者的訂閱費用購買的，再次感謝支持🙏

結論

以上就是我使用 SwiftUI 文件工具的心得與經驗。

必須要說，真的很謝謝各位付費支持我寫此專欄的朋友們，不然我也不見得會去買那些工具來試用，然後寫出這篇文章。很享受這個取之於讀者、用之於讀者的循環！

喜歡這篇文章的話，請到 Patreon 訂閱支持我🙏

我的目標是累積到 100 位支持者，目前 27%。也可以按下愛心❤️、留言💬、回信✉️與我交流。這些回饋都會直接影響到我繼續寫作的動力與頻率喔。

希望今天的內容可以加速你掌握的 SwiftUI。我們下一期見！