Christy RichText

Christy RichText 是一個基於 Vue 3 與 Tiptap 的富文字編輯器套件，適合用在後台管理系統、文章編輯、公告內容、商品描述、醫療紀錄、飯店介紹、婚禮網站內容管理等需要輸入格式化文字的場景。

本套件為付費授權軟體。安裝套件不代表已取得合法使用權，正式使用前請先購買授權，並將授權碼填入專案設定檔。

主要功能

• 支援 Vue 3
• 支援 Nuxt 3
• 支援 TypeScript
• 支援 v-model
• 支援粗體、斜體、底線、刪除線
• 支援標題、段落、清單、引用
• 支援文字顏色、背景標記、字型、字級
• 支援表格
• 支援圖片插入
• 支援圖片雲端上傳
• 支援 Word 匯入
• 支援 Word 匯出
• 可作為表單輸入元件使用
• 可透過授權碼驗證訂閱狀態

使用前準備

請先確認你的專案使用：

Vue 3
Vite 或 Nuxt 3
Node.js 20.19 以上，或 Node.js 22.12 以上

安裝

在你的 Vue 或 Nuxt 專案中執行：

npm install christy-richtext

安裝完成後，套件會嘗試自動建立這個檔案：

public/christy-richtext.config.json

內容如下：

{
  "licenseKey": ""
}

請將你購買後取得的授權碼填入 licenseKey：

{
  "licenseKey": "你的授權碼"
}

客戶不需要設定 API 網址。授權驗證 API 是套件內部用來連接 Christy RichText 官方後端的設定，上架前會由套件作者切換為正式環境。

如果你的公司環境停用 npm install scripts，檔案可能不會自動產生。這時請手動建立：

public/christy-richtext.config.json

授權設定檔說明

licenseKey

購買 Christy RichText 後取得的授權碼。

{
  "licenseKey": "XXXX-XXXX-XXXX-XXXX"
}

補充：客戶設定檔只需要填寫 licenseKey。

Vue 3 使用方式

1. 在 main.ts 註冊套件

import { createApp } from 'vue'
import App from './App.vue'

import ChristyRichText from 'christy-richtext'
import 'christy-richtext/style.css'

const app = createApp(App)

// 這段控制「安裝 Christy RichText 套件」。
// 不需要在這裡寫授權碼，套件會自動讀取 public/christy-richtext.config.json。
app.use(ChristyRichText)

app.mount('#app')

2. 在頁面中使用編輯器

<script setup lang="ts">
import { ref } from 'vue'

// 這段控制「編輯器輸出的 HTML 內容」。
const content = ref('<p>開始輸入內容...</p>')
</script>

<template>
  <RichTextEditor v-model="content" />

  <h3>HTML 輸出</h3>
  <pre>{{ content }}</pre>
</template>

Vue 3 不使用全域註冊的方式

如果你不想在 main.ts 使用 app.use()，也可以在單一頁面直接引入元件。

<script setup lang="ts">
import { ref } from 'vue'
import { RichTextEditor } from 'christy-richtext'
import 'christy-richtext/style.css'

const content = ref('')
</script>

<template>
  <RichTextEditor v-model="content" />
</template>

這種方式仍然可以透過 public/christy-richtext.config.json 驗證授權。

Nuxt 3 使用方式

Nuxt 3 建議用 Plugin 註冊，並且只在瀏覽器端載入。

1. 建立 Plugin

建立檔案：

plugins/christy-richtext.client.ts

內容：

import ChristyRichText from 'christy-richtext'
import 'christy-richtext/style.css'

export default defineNuxtPlugin((nuxtApp) => {
  // 這段控制「在 Nuxt Client 端註冊 Christy RichText」。
  nuxtApp.vueApp.use(ChristyRichText)
})

2. 在頁面使用

<script setup lang="ts">
import { ref } from 'vue'

const content = ref('')
</script>

<template>
  <ClientOnly>
    <RichTextEditor v-model="content" />
  </ClientOnly>
</template>

3. Nuxt 授權設定檔位置

請確認你的 Nuxt 專案有這個檔案：

public/christy-richtext.config.json

Nuxt 啟動後，瀏覽器要能讀到：

/christy-richtext.config.json

授權驗證流程

套件啟動時會執行以下流程：

1. 讀取 public/christy-richtext.config.json
2. 取得 licenseKey
3. 呼叫 /license/validate
4. 後端檢查授權碼是否有效
5. 後端檢查訂閱是否啟用
6. 後端檢查授權是否過期
7. 後端檢查目前網站網域是否被授權
8. 驗證成功後，後端寫入 richtext_license Cookie

白話說明：

licenseKey 像會員卡號。
後端會檢查這張會員卡是否存在、是否過期、是否能在目前這個網站使用。

手動傳入授權碼

一般客戶不需要這樣做，建議使用 public/christy-richtext.config.json。

如果你需要在程式中手動傳入，也可以：

app.use(ChristyRichText, {
  licenseKey: 'XXXX-XXXX-XXXX-XXXX'
})

優先順序如下：

1. app.use() 手動傳入的 licenseKey
2. public/christy-richtext.config.json 裡的 licenseKey

圖片上傳

Christy RichText 支援兩種圖片上傳方式。

方式一：使用內建 API

如果你已完成授權驗證，並且後端有提供：

POST /api/images/upload

可以在 Demo 或自訂頁面中呼叫你的 API 上傳圖片。

方式二：自訂 uploadHandler

如果你想接自己的圖片上傳 API，可以傳入 uploadHandler。

<script setup lang="ts">
import { ref } from 'vue'
import { RichTextEditor } from 'christy-richtext'

const content = ref('')

// 這段控制「自訂圖片上傳」。
// file 是使用者選擇的圖片檔，最後要回傳圖片網址。
const uploadHandler = async (file: File): Promise<string> => {
  const formData = new FormData()
  formData.append('file', file)

  const response = await fetch('/api/images/upload', {
    method: 'POST',
    body: formData,
    credentials: 'include'
  })

  const data = await response.json()
  return data.url
}
</script>

<template>
  <RichTextEditor
    v-model="content"
    :upload-handler="uploadHandler"
  />
</template>

方式三：使用 uploadUrl

如果你只想給一個上傳網址，也可以使用 uploadUrl。

<template>
  <RichTextEditor
    v-model="content"
    upload-url="/api/images/upload"
  />
</template>

常用 Props

| Prop | Type | Default | 說明 | |---|---|---|---| | modelValue | string | '' | 編輯器的 HTML 內容 | | placeholder | string | '' | 編輯器提示文字 | | editable | boolean | true | 是否允許編輯 | | showWordCount | boolean | true | 是否顯示字數 | | defaultFontSize | string \| number | 16 | 預設字級 | | uploadHandler | (file: File) => Promise<string> | null | 自訂圖片上傳方法 | | uploadUrl | string | null | 圖片上傳 API 網址 |

常用 Events

| Event | Payload | 說明 | |---|---|---| | update:modelValue | string | 編輯器內容變更時觸發 | | change | string | 編輯器內容變更時觸發 |

表單送出範例

<script setup lang="ts">
import { ref } from 'vue'

const title = ref('')
const content = ref('')

// 這段控制「送出文章」。
const submit = async () => {
  const payload = {
    title: title.value,
    content: content.value
  }

  console.log('送出的資料：', payload)
}
</script>

<template>
  <form @submit.prevent="submit">
    <input
      v-model="title"
      type="text"
      placeholder="請輸入標題"
    />

    <RichTextEditor v-model="content" />

    <button type="submit">
      送出
    </button>
  </form>
</template>

後端儲存內容時的注意事項

Christy RichText 輸出的是 HTML 字串，例如：

<p>這是一段文字</p>

你可以把它存到資料庫的 nvarchar(max) 或類似欄位。

建議資料表欄位：

Content NVARCHAR(MAX) NOT NULL

如果內容是由使用者輸入，顯示到前台時請注意 XSS 風險。

簡單說：

富文字內容本質上是 HTML。
HTML 如果沒有處理好，可能被惡意塞入 script。

建議在後端儲存或前端顯示前，依你的系統需求做 HTML 清理。

常見問題

1. 安裝後沒有產生 public/christy-richtext.config.json

可能原因：

npm install scripts 被停用
使用 npm install --ignore-scripts
公司環境封鎖 postinstall
套件管理器安全政策阻擋

解法：手動建立檔案。

public/christy-richtext.config.json

內容：

{
  "licenseKey": "你的授權碼"
}

2. 顯示「缺少 Christy RichText 授權碼」

請檢查：

public/christy-richtext.config.json 是否存在
licenseKey 是否已填入
JSON 格式是否正確
瀏覽器是否能打開 /christy-richtext.config.json

3. 顯示「授權碼無效」

可能原因：

授權碼輸入錯誤
授權已停用
授權已過期
後端資料庫沒有這筆授權

4. 顯示「網域未獲得授權」

代表授權碼存在，但目前網站網域不在授權清單內。

請確認購買授權時提供的網域是否正確，例如：

example.com
www.example.com
localhost

注意：

example.com 和 www.example.com 可能會被視為不同網域。

5. Nuxt 頁面出現 window 或 document 錯誤

請確認：

Plugin 檔名使用 .client.ts
頁面使用 <ClientOnly>

6. 樣式沒有出現

請確認有引入 CSS：

import 'christy-richtext/style.css'

更新套件

npm update christy-richtext

或指定版本：

npm install christy-richtext@latest

更新後，請確認你的設定檔仍然存在：

public/christy-richtext.config.json

授權條款

Christy RichText 是專有授權軟體，不是 MIT、Apache、GPL 等開源免費授權。

購買授權後，你可以在授權範圍內用於商業專案、客戶專案、付費網站、付費應用程式或企業內部系統。

你不可以：

• 未購買授權就使用
• 將本套件重新販售
• 將本套件重新包裝後販售
• 修改、重新編譯、改名後作為自己的套件販售
• 將本套件作為範本、主題、SDK、函式庫或市集商品再散布
• 超出購買方案允許的專案數、網域數、使用者數或使用期間

完整條款請見：

LICENSE

技術支援

如果遇到問題，請提供以下資訊，方便判斷：

1. 使用的 Vue / Nuxt 版本
2. 使用的 Node.js 版本
3. christy-richtext 版本
4. 錯誤訊息截圖
5. 瀏覽器 Console 錯誤
6. Network 裡 /license/validate 的回應
7. public/christy-richtext.config.json 是否存在，不要提供完整 licenseKey

為了安全，請不要在公開 issue、截圖或聊天中貼出完整授權碼。