Documentation

把彩虹富文字編輯器接進 Vue / Nuxt 專案。

從安裝、授權設定到 Nuxt client plugin，照著順序完成基本整合；後面再補上 API、圖片上傳、送出流程與 HTML 顯示安全提醒。

Nuxt 3 client pluginVue 3 v-modelUpload / API
01

Install

先確認環境並安裝套件。

彩虹富文字編輯器支援 Vue 3、Vite 與 Nuxt 3。建議使用 Node.js 20.19 以上，或 Node.js 22.12 以上。 

npm install christy-richtext
02

License

建立授權設定檔。

安裝套件不代表已取得授權。正式使用前，請把購買後取得的授權碼放在 public/christy-richtext.config.json。 Nuxt 啟動後，瀏覽器需要能讀到 /christy-richtext.config.json。 

// public/christy-richtext.config.json
{
  "licenseKey": "你的授權碼"
}
03

Vue 3

在 Vue 3 專案註冊並使用。

如果是一般 Vue 3 專案，建議在 main.ts 使用 app.use() 註冊套件，再於頁面用 v-model 接收 HTML 字串。

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)

// 這段控制「安裝 彩虹富文字編輯器套件」。
// 不需要在這裡寫授權碼，套件會自動讀取 public/christy-richtext.config.json。
app.use(ChristyRichText)

app.mount('#app')

頁面使用

<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>
04

Nuxt

Nuxt 3 建議用 client plugin 註冊。

富文字編輯器會使用瀏覽器 API。Nuxt 專案請先建立 plugins/christy-richtext.client.ts，只在瀏覽器端註冊套件與載入 CSS；頁面再用 ClientOnly 包住編輯器。

plugins/christy-richtext.client.ts

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

export default defineNuxtPlugin((nuxtApp) => {
  // 這段控制「在 Nuxt Client 端註冊彩虹富文字編輯器」。
  nuxtApp.vueApp.use(ChristyRichText)
})

頁面使用

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

// 控制富文字內容
const content = ref('')
</script>

<template>
  <!-- ClientOnly 可以避免 SSR 階段碰到瀏覽器 API -->
  <ClientOnly>
    <RichTextEditor
      v-model="content"
      placeholder="請輸入公告內容..."
      :show-word-count="true"
      :default-font-size="18"
    />
  </ClientOnly>
</template>
05

API

常用 Props 與 Events。

下方列出 README 裡公開的常用 API。文件表格使用元件正式 prop 名稱；在 Vue template 裡也可以使用 kebab-case，例如 show-word-count。

Props

modelValuestring
編輯器的 HTML 內容。搭配 v-model 使用。
placeholderstring
編輯器沒有內容時的提示文字。
editableboolean
是否允許編輯。預設為 true。
showWordCountboolean
是否顯示字數統計。template 可寫成 show-word-count。
defaultFontSizestring | number
預設字級。template 可寫成 default-font-size。
uploadHandler(file: File) => Promise<string>
自訂圖片上傳方法，最後需要回傳圖片網址。
uploadUrlstring
圖片上傳 API 網址。

Events

update:modelValuestring
內容更新時回傳 HTML 字串。
changestring
編輯器內容變更時觸發。
06

Upload

圖片上傳可以用 uploadHandler 或 uploadUrl。

如果你要接自己的圖片 API，可以傳入 uploadHandler。如果只需要指定一個上傳網址，也可以直接使用 uploadUrl。

自訂 uploadHandler

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

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

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

Workflow

送出時，HTML 只是 payload 的一個欄位。

實務上會和標題、分類、狀態一起送到 API，而不是只送一段內容。

  1. 編輯內容
  2. 取得 HTML
  3. 組成表單 payload
  4. 送到 API
  5. 清理後儲存
  6. 前台安全顯示
async function submitArticle() {
  const payload = {
    title: form.title,
    categoryId: form.categoryId,
    status: form.status,
    contentHtml: content.value,
  }

  await $fetch('/api/articles', {
    method: 'POST',
    body: payload,
  })
}
08

Security

HTML 顯示安全提醒

彩虹富文字編輯器輸出的是 HTML 字串，適合用來儲存文章、公告或商品描述等富文字內容。

編輯器本身只負責產生內容，但實際顯示時，如果你把資料庫取出的 HTML 直接用 v-html 或 innerHTML 顯示，仍建議依照你的系統需求做 HTML 清理。

白話來說：編輯器輸出的內容像一份帶格式的文件。文件本身可以正常使用，但如果內容來源包含使用者輸入、匯入資料或外部 API，就建議在儲存前或顯示前檢查一次，只保留允許的 HTML 標籤與屬性，避免不安全內容被顯示到前台。