URichText：编辑 HTML 正文

URichText 使用 wangEditor 原生 API，负责工具栏、编辑器实例和销毁。model 是 HTML 字符串，不是纯文本或 Markdown。

安装与完整示例

pnpm add @wangeditor/editor@^5.1

只需 editor，不需要 @wangeditor/editor-for-vue。组件内部已引入 wangEditor CSS。

<script setup lang="ts">
import { ref } from 'vue'
import { useI18n } from 'vue-i18n'
import URichText from '@uadmin/ui/components/URichText.vue'

const props = defineProps<{ initialHtml?: string; save: (html: string) => Promise<void> }>()
const { t } = useI18n({
  useScope: 'local',
  messages: {
    'zh-CN': { placeholder: '输入文章内容', save: '保存', preview: '只读模式' },
    'en-US': { placeholder: 'Write article content', save: 'Save', preview: 'Read-only mode' },
  },
})
const html = ref(props.initialHtml ?? '')
const readonly = ref(false)
const saving = ref(false)
async function save() {
  saving.value = true
  try {
    await props.save(html.value)
  } finally {
    saving.value = false
  }
}
</script>

<template>
  <el-switch v-model="readonly" :active-text="t('preview')" />
  <URichText
    v-model="html"
    :readonly="readonly"
    :placeholder="t('placeholder')"
    :height="360"
    mode="simple"
  />
  <el-button type="primary" :loading="saving" @click="save">{{ t('save') }}</el-button>
</template>

父组件提供持久化函数，并通过自己的 HTTP/错误处理层显示保存失败。示例初始化一次正文；切换正在编辑的文章时，父层应显式更新 model 或重建页面。

API

Prop	类型	默认 / 行为
modelValue	string	''；HTML，外部变化通过 setHtml 同步
placeholder	string	内置本地化占位文案
height	number | string	360；只控制正文区域，不含工具栏
mode	'default' | 'simple'	'default'
toolbarConfig	Partial<IToolbarConfig>	传给 createToolbar
editorConfig	Partial<IEditorConfig>	传给 createEditor 的 config
readonly	boolean	false；变化时调用 disable/enable

Event / Method	参数 / 行为
update:modelValue	HTML 字符串，来自 editor.getHtml()
blur	wangEditor IDomEditor 实例
getEditor()	当前实例；初始化前、卸载后为 null

没有自定义插槽。类型 IEditorConfig/IToolbarConfig/IDomEditor 从 @wangeditor/editor 导入。

配置与生命周期边界

工具栏示例采用 wangEditor 配置，而不是 URichText 自定义的按钮数组：

import type { IToolbarConfig } from '@wangeditor/editor'

const toolbarConfig: Partial<IToolbarConfig> = {
  excludeKeys: ['uploadImage', 'uploadVideo'],
}

<URichText v-model="html" :toolbar-config="toolbarConfig" />

mode、placeholder、toolbarConfig 和 editorConfig 在创建时读取，挂载后不会自动重建实例。必须切换这些配置时，通过 Vue key 重建组件，并先保留 model。readonly 和 model 可响应式更新。

editorConfig 在默认 placeholder/readOnly 后展开，因此可覆盖这两个初始设置；不要同时配置相互矛盾的 readonly 与 readOnly。组件自身随后设置 onChange/onBlur，传入同名回调不会替代组件的 model/blur 通知。

上传与内容安全

富文本图片上传不使用 UUpload 的 customRequest 或注入处理器，应在 wangEditor 的 editorConfig.MENU_CONF 中配置所需菜单。没有配置后端时，不应展示会让用户误以为已保存附件的上传功能；可先从工具栏排除对应菜单。

正文保存与渲染前应由应用按自己的允许标签策略处理不可信 HTML。URichText 不提供 HTML 清洗，也不把业务接口结果自动保存。

相关：文件上传契约 · 页面状态与卸载 · JSON 编辑