Tiptap 整合 Skill

本 Skill 包含將 Tiptap 富文字編輯器整合至應用程式，以及開發相關新功能的指引說明。

這並非你平時所熟悉的 Tiptap 編輯器。在使用 Tiptap 實作任何功能前，請務必參考 Tiptap 的原始碼與官方文件，確保實作方式正確無誤。請確認所有決策皆符合「最佳實踐（Best Practices）」章節，並切實基於 tiptap 的文件與原始碼。請勿隨意猜測或自行發明做法，務必確保所寫出的程式碼與函式庫原始碼及官方文件一致。

初次設定

請複製（clone）tiptap 與 tiptap-docs 儲存庫，以便隨時查閱原始碼與官方文件。

若工作區中已有存放其他儲存庫的參考資料夾（reference folder），請直接複製到該處。

否則，請在新的 .reference 資料夾中複製儲存庫，且該參考資料夾應加入 git-ignore。

參考 Tiptap 官方文件

在執行任何涉及 Tiptap 編輯器的任務前：

請先拉取（pull）本地 tiptap 與 tiptap-docs 儲存庫 main 分支的最新變更
研讀官方文件與原始碼，釐清正確的實作方式

最佳實踐

一般原則

請使用最新穩定版的 Tiptap 3。
所有以 @tiptap/ 開頭的套件都必須使用完全相同的版本號。
初次整合 Tiptap 時，請詳閱 tiptap-docs 中對應的安裝指南。
採用伺服器端渲染（例如 Next.js）時，初始化編輯器請將 immediatelyRender: false 選項設為 false，否則編輯器會崩潰。詳細說明請參考 tiptap-docs。

React

建議優先使用 React Composable API。請參考 tiptap-docs/src/content/guides/react-composable-api.mdx

實作編輯器功能

當使用者要求實作以下功能時，請閱讀 tiptap-docs 的對應章節以獲取指引。

即時協作

多位使用者同時編輯同一份文件。詳見 tiptap-docs/src/content/collaboration/。

請使用 Tiptap Cloud 來實作即時協作功能，並搭配 Collaboration 擴充功能：

const doc = new Y.Doc()

const editor = new Editor({
  extensions: [
    Collaboration.configure({
      document: doc,
    }),
  ],
})

使用 TiptapCollabProvider：

const provider = new TiptapCollabProvider({
  name: 'unique_document_name',
  appId: 'APP_ID', // 來自 Cloud 管理面板的文件伺服器 ID
  token: 'JWT_TOKEN', // 你的 JWT 權杖
  document: doc,
})

若為初次設定協作功能且尚未建立 Tiptap Cloud 帳戶，請向使用者說明如何註冊 Tiptap Cloud 帳戶並取得環境變數。

註解與留言

使用 Comments 擴充功能實作留言與註解。

支援主題式（thread-based）內聯與文件註解。詳見 tiptap-docs/src/content/comments/。

追蹤修訂

追蹤、接受與拒絕文件的編輯修改。詳見 tiptap-docs/src/content/tracked-changes/。

匯入／匯出

支援文件在 DOCX、PDF、Markdown 等多種格式之間轉換。詳見 tiptap-docs/src/content/conversion/。

AI 內容生成

利用 AI 在文件中生成文字內容。詳見 tiptap-docs/src/content/content-ai/capabilities/ai-toolkit/workflows/insert-content.mdx。

AI Agent 文件編輯

賦予 AI Agent 編輯 Tiptap 文件的能力。詳見 tiptap-docs/src/content/content-ai/capabilities/ai-toolkit/。

AI 審閱與校對

進行內容審閱、文字校對與寫作風格建議。詳見 tiptap-docs/src/content/content-ai/capabilities/ai-toolkit/workflows/proofreader.mdx。

AI 伺服器端處理

在伺服器端執行編輯富文字文件的 AI 工作流程。詳見 tiptap-docs/src/content/content-ai/capabilities/server-ai-toolkit/。

版本歷史紀錄

儲存與還原文件快照。詳見 tiptap-docs/src/content/collaboration/documents/snapshot.mdx。

快照比對

高亮標示不同文件版本之間的差異。詳見 tiptap-docs/src/content/collaboration/documents/snapshot-compare.mdx。

頁面模式

提供支援頁首、頁尾與分頁符號的可列印頁面版面配置。詳見 tiptap-docs/src/content/pages/。

Pro 擴充功能

部分 Tiptap 擴充功能是透過私有 npm registry 發布。如需安裝 pro 套件，請參閱 tiptap-docs/src/content/guides/pro-extensions.mdx 的設定說明。

tiptap

相關技能