Writing Tools API：應用程式如何接入 Apple Intelligence 的書寫層

Apple Intelligence 的書寫層（品牌名為 Writing Tools）在每一台啟用 Apple Intelligence 的 iOS 18+ 裝置上都會隨附。使用者選取文字、點按 Writing Tools 選單，即可獲得校對、改寫（友善、專業、簡潔）、摘要、清單與表格生成，以及（自 iOS 18.2 起）生成式撰寫¹。此功能位於系統層，而非任何單一應用程式內，使用者期望它在每一個文字輸入欄位都能運作。

使用 UITextView、NSTextView 或 WKWebView 的應用程式無需撰寫程式碼即可獲得整合，前提是該文字檢視運行於 TextKit 2 之上²。具有自訂文字引擎的應用程式則需要 UIWritingToolsCoordinator API 才能將其文字儲存與渲染接入 Writing Tools 體驗。本文將對照 Apple 文件梳理 API 介面、命名三個採用層級，並涵蓋何時應選擇退出（因為並非每個文字輸入都應接受生成式改寫）。

TL;DR

• 運行於 TextKit 2 的標準文字檢視（UITextView、NSTextView、WKWebView）可免費獲得 Writing Tools，並完整提供帶動畫的內嵌改寫體驗²。
• 自訂文字檢視採用 UITextInteraction 即可獲得快顯／情境選單整合，無需額外程式碼；完整的內嵌整合則需要 UIWritingToolsCoordinator API³。
• UIWritingToolsBehavior 是單一列舉屬性，用以控制體驗層級：.complete、.limited 或 .none⁴。.default 值是一個由系統在執行階段解析為這三者之一的請求；它並非第四個層級。對於敏感文字（密碼、原始碼編輯器、使用者不希望被改寫的聊天欄位），請設為 .none。
• allowedWritingToolsResultOptions 讓應用程式宣告可接受的輸出形式（純文字、富文字、清單、表格，或 iOS 26 中的 .presentationIntent），如此 Writing Tools 就不會回傳應用程式無法渲染的內容⁵。
• 與代理工作流的關聯：Writing Tools 與 App Intents、Foundation Models 同樣是 Apple Intelligence 的介面，但作用於文字輸入層，而非動作層。

Writing Tools 實際做了什麼

iOS 18+ 中的 Writing Tools 選單提供針對選取文字的一組操作。根據 Apple 開發者文件與 WWDC 2024 介紹，目前的公開操作集如下⁶：

校對（Proofread）。 修正文法、拼字、標點與用字。回傳一份差異，使用者可接受、拒絕或逐項檢視。

改寫（Rewrite）。 三種預設語氣（友善、專業、簡潔），加上一個「描述你想要的變更」自訂提示。模型會以所選語氣改寫選取的文字。

摘要（Summarize）。 將長文變短。變化形式包括「摘要」、「重點」、「清單」、「表格」。由使用者選擇形式。

撰寫（Compose）。 由提示生成式撰寫（iOS 18.2+）。使用者描述想要的內容；模型會生成新文字，而非改寫既有文字。

驅動 Writing Tools 的模型，在支援的硬體上是 Apple 的裝置端基礎模型，較大的請求則會回退至私有雲端¹。使用者的文字絕不會傳送給第三方。隱私敘事是其價值主張的一部分。

三個採用層級

應用程式根據需要的 Writing Tools 整合程度，落入三個分類之一。

層級 1：標準文字檢視（零程式碼）

使用 UITextView、NSTextView 或 WKWebView 進行文字輸入的應用程式，無需撰寫任何程式碼即可獲得 Writing Tools，前提是該文字檢視使用 TextKit 2²。系統會處理選單、內嵌改寫 UI、動畫，以及校對的內嵌標示。應用程式的工作就是使用標準文字檢視。

let textView = UITextView()
textView.text = "Original content."
textView.isEditable = true
// Writing Tools just works.

TextKit 2 的要求很重要，因為 TextKit 1 採用不同的版面架構，不支援內嵌改寫動畫。針對 iOS 18+ 的新應用程式應預設使用 TextKit 2；舊應用程式可能需要遷移步驟。當透過 Interface Builder 或現代初始化器建立時，UITextView 在 iOS 16+ 上預設為 TextKit 2。

層級 2：搭配 UITextInteraction 的自訂文字檢視（僅快顯）

具有自訂文字檢視的應用程式可以採用 UITextInteraction，即可在快顯列與情境選單中獲得 Writing Tools，無需額外程式碼⁷。使用者可以喚起 Writing Tools、看到校對／改寫／摘要的面板式介面，並接受或拒絕結果。結果透過標準的貼上／取代流程交付給應用程式。

此整合是部分的：應用程式不會獲得內嵌動畫或校對的內嵌標示。那些需要完整的協調器。對於大多數具有自訂文字檢視的應用程式而言，採用 UITextInteraction 已經足夠。

層級 3：UIWritingToolsCoordinator（完整內嵌體驗）

希望以自訂文字儲存獲得完整 Writing Tools 體驗的應用程式，應採用 UIWritingToolsCoordinator（或 macOS 上的 NSWritingToolsCoordinator）³。協調器管理 Writing Tools 與應用程式之間的雙向對話：

• 應用程式向協調器提供文字情境（一個 NSAttributedString，代表目前選取範圍以及選擇性的周圍段落）。
• 協調器管理面板 UI 與內嵌動畫。
• 協調器透過委派回呼，在應用程式的文字儲存中插入、取代或產生文字變更動畫。

UIWritingToolsCoordinator.Delegate 上的關鍵委派方法（已對照 iOS 26 SDK 標頭驗證）³：

• writingToolsCoordinator(_:requestsContextsForScope:completion:)。輸入端方法。Writing Tools 在指定範圍內向應用程式請求相關文字情境（每一個都是 NSAttributedString 加上一個選取範圍）。應用程式從其文字儲存建構情境並回傳。
• writingToolsCoordinator(_:replaceRange:inContext:proposedText:reason:animationParameters:completion:)。文字變更的主力方法。Writing Tools 為某情境內的某範圍提出新文字；應用程式將變更套用至其儲存並確認。
• writingToolsCoordinator(_:finishTextAnimation:forRange:inContext:completion:)。當某範圍的文字動畫（原文與改寫文字之間的變形）完成時呼叫。並非工作階段結束的訊號。
• writingToolsCoordinator(_:willChangeToState:completion:)。工作階段生命週期訊號。協調器會在多個狀態間轉換（idle、interactive、noninteractive 等），並在每次轉換前通知委派。應用程式在此回應「工作階段開始」與「工作階段結束」。

協調器 API 是為序列化文字引擎（TextKit 風格）、文件型編輯器，以及希望部分整合的程式碼編輯器所設計。Apple 在 WWDC 2025 的「Dive deeper into Writing Tools」議程⁸中講解了多段落、多樣式的情境。請注意，UIWritingToolsCoordinator 是在 iOS 18.2 首次以公開 API 形式推出；iOS 26 是深化它，而非引入它。

行為屬性：UIWritingToolsBehavior

最重要的單一啟用／停用控制，是 UITextView、UITextField 以及任何符合 UITextInputTraits 的檢視上的 writingToolsBehavior 屬性⁴：

textView.writingToolsBehavior = .complete   // full inline experience
textView.writingToolsBehavior = .limited    // panel-only (no inline rewrite)
textView.writingToolsBehavior = .none       // disabled entirely
textView.writingToolsBehavior = .default    // request system default

其中三個值是真正的體驗層級；.default 則是一個請求，由系統根據文字輸入的特徵解析為其他三者之一：

• .complete。 完整的 Writing Tools 體驗，包括內嵌改寫動畫、內嵌校對標示與面板。最適合長篇文字編輯器（Mail 撰寫器、Notes、文件編輯器）。
• .limited。 僅面板式體驗。使用者可在選單中看到 Writing Tools，但改寫發生在面板中而非內嵌。最適合較短的文字欄位，因為內嵌動畫在這些情境下會顯得不成比例。
• .none。 此文字輸入停用 Writing Tools。用於敏感內容。
• .default。 是一個請求，而非一個層級。標頭文件記載解析後的值永遠會是 .none、.limited 或 .complete 之一；唯讀的 behavior 屬性永遠不會回傳 .default。除非有特定理由覆寫，大多數應用程式應將該屬性保留為 .default。

何時應選擇退出

有三類文字輸入適合設為 .none：

密碼與敏感憑證。 密碼欄位絕不應提供「以友善語氣改寫此處」的選項。使用者輸入的是不能被轉換的字面文字。Apple 的 UITextField 在 isSecureTextEntry = true 時已預設停用 Writing Tools；明確設為 .none 屬於雙重保險。

原始碼編輯器。 SwiftUI 程式碼編輯器或技術內容用的 Markdown 編輯器，不會因為被要求以「專業」語氣改寫所選程式碼而獲得改進。Writing Tools 的改寫路徑是針對自然語言調校的，而非語法結構。對於內容並非自然語言的文字檢視，請設為 .none。

改寫會改變意圖的聊天欄位。 訊息應用程式或留言欄位，使用者的精確用字至關重要（涉及語氣、聲音、責任歸屬），可能希望省略改寫但保留校對。Writing Tools 目前的 API 不允許按動作分別控制；.none 值會停用整個體驗。務實的做法是對於偶爾適合改寫但不應預設內嵌出現的欄位採用 .limited（僅面板，使用者必須刻意喚起）。

allowedWritingToolsResultOptions 宣告應用程式可渲染的內容

一個更細緻的控制位於 UITextInputTraits.allowedWritingToolsResultOptions（也以 UITextView.allowedWritingToolsResultOptions 形式公開）⁵。該屬性是一個 UIWritingToolsResultOptions 選項集，宣告應用程式的文字檢視可渲染的內容形式：

• .plainText。文字檢視支援純文字（無格式屬性）。
• .richText。支援格式化文字（粗體、斜體等）。
• .list。支援清單渲染（項目符號、編號）。
• .table。支援表格渲染。
• .presentationIntent（iOS 26+）。支援豐富的語意意圖標記（標題、區塊引用、程式碼區塊），使用 Foundation 框架的 PresentationIntent 型別，是比純富文字更豐富的介面。

設定後，Writing Tools 會將其輸出限制在應用程式可接受的形式內。一個僅宣告 .plainText 的純文字編輯器，不會收到「將此做成表格」的建議。一個宣告 .richText 與 .list 但不宣告 .table 的富文字編輯器，會獲得清單輸出，但不會獲得表格輸出。

預設值是 .default，會讓系統根據文字檢視的特徵自行選擇。當自動偵測產生錯誤的形式時（例如某個文字檢視能夠渲染富文字，但應用程式的資料模型只儲存純文字），請明確設定該屬性。

輸出落在何處

對於層級 1 的應用程式（標準文字檢視），輸出會透過標準文字檢視機制內嵌取代選取內容。不涉及任何應用程式程式碼。

對於層級 2 的應用程式（搭配 UITextInteraction 的自訂檢視），輸出透過標準的貼上流程到達。處理變更的是文字檢視的 UITextInput 協定實作。已正確實作 UITextInput 的應用程式，只要加入 UITextInteraction，就能「免費」獲得整合。

對於層級 3 的應用程式（完整協調器），輸出透過委派的 replaceRange: 方法到達。應用程式將變更套用至其文字儲存、在完成處理常式中回傳新的文字界限，協調器則處理視覺轉場。應用程式仍然是文字儲存的真實來源。

WWDC 2025 深入講解新增的內容

WWDC 2025 的「Dive deeper into Writing Tools」議程⁸沿三個值得命名的軸向擴充了 iOS 18 API：

多段落情境。 應用程式現在可以向協調器提供更多周圍情境，讓 Writing Tools 能夠處理依賴周圍段落的選取（例如某句話的意義取決於上方的段落）。

自訂改寫提示。 iOS 18.2 beta 中的「描述你想要的變更」路徑已完全公開，並提供委派掛鉤，讓想要在傳給模型前檢視或轉換使用者提示的應用程式得以介入。

更佳的混合內容處理。 跨越多種樣式或包含內嵌圖片的文字選取，現在會透過協調器流動，內嵌內容會被保留為不透明範圍。協調器不會嘗試改寫內嵌圖片；它會保留圖片並改寫周圍的文字。

這些差異是 iOS 18 模型的擴充，而非取代。已採用 iOS 18 Writing Tools API 的應用程式仍會繼續運作；iOS 26 為需要的應用程式解鎖更深層的整合。

與代理工作流的連結

Writing Tools 是第三方應用程式可整合的三個 Apple Intelligence 介面之一：

Writing Tools。 文字輸入層。使用者選取文字、要求系統轉換它、內嵌獲得結果。應用程式透過提供格式良好的文字檢視，並（選擇性地）實作協調器來參與。使用者喚起；應用程式接收結果。

App Intents。 動作層。使用者（或代理）要求 Apple Intelligence 執行某動作；系統將請求路由至應用程式中已註冊的 intent。應用程式透過宣告 AppIntent 型別、參數結構描述與結果型別來參與。詳見 App Intents 是 Apple 接入應用程式的新 API。

Foundation Models。 執行階段 LLM 層。應用程式透過 Foundation Models 框架直接喚起裝置端 LLM，用於應用程式內生成。詳見 Foundation Models 裝置端 LLM。

這三個介面是可組合的。一個筆記應用程式可能會使用 Writing Tools（用於使用者基於選取的改寫）、App Intents（用於「摘要我昨天的筆記」），以及 Foundation Models（用於應用程式內的生成式功能，例如自動標籤）。每一層都是不同的整合，對應不同的使用者心智模型。

App Intents 與 MCP Tools 文章涵蓋何時應透過 App Intents（Apple Intelligence）暴露動作，相對於透過 MCP 伺服器（通用代理）。Writing Tools 不在這個問題之內；它是系統級介面，在本叢集所涵蓋的內容中沒有第三方代理的對應物。

此模式對 iOS 26+ 應用程式的意義

三個重點。

1. 預設使用標準文字檢視與 TextKit 2。 大多數應用程式不需要協調器 API。如果應用程式的文字輸入是 UITextView 或 WKWebView，Writing Tools 無需程式碼即可運作；如果應用程式仍在使用 TextKit 1，工作量在於 TextKit 2 的遷移。

2. 針對敏感輸入，刻意設定 writingToolsBehavior = .none。 密碼、程式碼編輯器、要求精確文字的欄位。預設會嘗試做正確的事，但明確設定是一項團隊可清楚說明的、可辯護的產品決策。

3. 僅在應用程式的文字引擎確實是自訂時，才動用 UIWritingToolsCoordinator。 Markdown 編輯器、程式碼編輯器、具有自訂渲染的文件應用程式、終端機式文字檢視。協調器是實質的工程投資；對大多數自訂檢視而言，層級 2（UITextInteraction）已經足夠。

完整 Apple 生態系叢集：型別化的 App Intents；MCP 伺服器；路由問題；Foundation Models；執行階段與工具 LLM 區別；三個介面；單一真實來源模式；兩個 MCP 伺服器；Apple 開發專用的 hooks；Live Activities；watchOS 執行階段；SwiftUI 內部；RealityKit 的空間心智模型；SwiftData 結構描述紀律；Liquid Glass 模式；多平台出貨；平台矩陣；Vision 框架；Symbol Effects；Core ML 推論；我拒絕撰寫的內容。中樞位於 Apple 生態系列。對於更廣泛的 iOS 與 AI 代理情境，請參閱 iOS 代理開發指南。

FAQ

我需要 Apple Intelligence 才能在我的應用程式中測試 Writing Tools 嗎？

若要測試完整的使用者體驗，是的。面向使用者的 Writing Tools 選單只會在啟用 Apple Intelligence 的裝置上出現（iPhone 15 Pro 或更新機型、M1 Mac 或更新機型，搭配 iOS 18+ / macOS 15+）。為開發目的，您可以在任何 iOS 18+ 模擬器或裝置上測試 API 整合，方式是檢查您的文字檢視是否暴露 isWritingToolsActive，以及委派方法是否正確接線；只是在沒有 Apple Intelligence 可用時，系統選單不會出現。

如果我在 iOS 18+ 應用程式中對 Writing Tools 不做任何事會怎樣？

對於標準文字檢視（UITextView、WKWebView），Writing Tools 會自動出現。對於沒有 UITextInteraction 的自訂文字檢視，Writing Tools 不會出現在選單中，使用者也無法在您的應用程式文字中喚起它。對於 Writing Tools 不適合出現的檢視（密碼欄位、程式碼編輯器），不做任何事是可辯護的預設；對於一般文字輸入，不做任何事意味著錯失使用者會尋找的系統功能。

.complete 與 .limited 之間的差異是什麼？

.complete 會以動畫內嵌執行 Writing Tools 改寫，將原文變形為改寫文字，並提供內嵌校對標示。.limited 會透過面板 UI 執行 Writing Tools；使用者在獨立介面中看到改寫，並決定是否套用。對於內嵌動畫能強化編輯流程的長篇文字編輯器使用 .complete；對於面板感覺較合適的較短文字欄位使用 .limited。

我可以自訂 Writing Tools 的提示或模型行為嗎？

模型與提示由系統控制。應用程式無法將自訂的改寫行為注入 Writing Tools 選單。對於應用程式專屬的生成式撰寫功能，請直接使用 Foundation Models 框架（詳見 Foundation Models 裝置端 LLM），並透過您自己的 UI 呈現該功能。

Writing Tools 如何處理混合選取（文字 + 圖片）？

根據 WWDC 2025 的「Dive deeper into Writing Tools」⁸，包含內嵌內容（圖片、附件）的混合選取會透過協調器流動，內嵌內容會被保留為不透明範圍。Writing Tools 會改寫周圍文字，但不會嘗試轉換內嵌內容。對於使用協調器的應用程式，委派會收到提議文字承載資料，其中內嵌內容的範圍會被標示為未變更。

References