API 概览

UEditor Plus Designer 提供了完整的 TypeScript 类型定义和丰富的 API。

主要模块

组件 API

• DesignerConfig - 编辑器配置接口
• DesignerInstance - 编辑器实例方法

数据类型

• MaterialTypes - 素材相关类型定义
• Events - 事件系统

快速导航

配置相关

import type { DesignerConfig } from 'ueditor-plus-designer'

const config: DesignerConfig = {
  ueditorPath: '/ueditor-plus',
  ueditorConfig: {},
  categoryLoader: async () => [],
  styleLoader: async (params) => ({ records: [], total: 0, page: 1, pageSize: 20 })
}

实例方法

import type { DesignerInstance } from 'ueditor-plus-designer'

const designerRef = ref<DesignerInstance | null>(null)

// 获取内容
const content = designerRef.value?.getContent()

// 设置内容
designerRef.value?.setContent('<div>content</div>')

素材类型

import type {
  MaterialCategory,
  MaterialItem,
  MaterialQueryParams,
  StyleListData
} from 'ueditor-plus-designer'

类型导出

UEditor Plus Designer 导出以下类型：

// 配置类型
export interface DesignerConfig
export interface UEditorConfig

// 实例类型
export interface DesignerInstance

// 素材类型
export interface MaterialCategory
export interface MaterialItem
export interface MaterialQueryParams
export interface StyleListData
export interface MaterialData

// 其他类型
export interface ImageItem
export interface VideoItem
export interface SectionData

使用示例

Vue 3

<script setup lang="ts">
import { ref } from 'vue'
import { UEditorPlusDesigner } from 'ueditor-plus-designer'
import type { 
  DesignerConfig,
  DesignerInstance,
  MaterialCategory,
  StyleListData
} from 'ueditor-plus-designer'

const designerRef = ref<DesignerInstance | null>(null)

const config: DesignerConfig = {
  ueditorPath: '/ueditor-plus',
  categoryLoader: async (): Promise<MaterialCategory[]> => {
    return []
  },
  styleLoader: async (): Promise<StyleListData> => {
    return {
      records: [],
      total: 0,
      page: 1,
      pageSize: 20
    }
  }
}

const handleReady = (): void => {
  if (designerRef.value) {
    const content: string = designerRef.value.getContent()
    console.log(content)
  }
}
</script>

React

import React, { useRef } from 'react'
import { UEditorPlusDesigner } from './components/UEditorPlusDesigner'
import type {
  DesignerConfig,
  DesignerInstance,
  MaterialCategory,
  StyleListData
} from './components/UEditorPlusDesigner'

function App() {
  const designerRef = useRef<DesignerInstance | null>(null)

  const config: DesignerConfig = {
    ueditorPath: '/ueditor-plus',
    categoryLoader: async (): Promise<MaterialCategory[]> => {
      return []
    },
    styleLoader: async (): Promise<StyleListData> => {
      return {
        records: [],
        total: 0,
        page: 1,
        pageSize: 20
      }
    }
  }

  const handleReady = (): void => {
    if (designerRef.current) {
      const content: string = designerRef.current.getContent()
      console.log(content)
    }
  }

  return (
    <UEditorPlusDesigner
      ref={designerRef}
      config={config}
      onReady={handleReady}
    />
  )
}

原生 JavaScript

// 创建实例
const designer = UEditorPlusDesigner.createDesigner({
  ueditorPath: '/ueditor-plus',
  categoryLoader: function() {
    return fetch('/api/categories')
      .then(res => res.json())
  },
  styleLoader: function(params) {
    return fetch('/api/materials')
      .then(res => res.json())
  }
})

// 监听事件
designer.on('ready', function() {
  console.log('Ready')
})

designer.on('change', function(content) {
  console.log('Content:', content)
})

// 挂载
designer.mount('#container')

// 调用方法
const content = designer.getContent()
designer.setContent('<div>New content</div>')

API 兼容性

版本兼容性

API	版本	说明
DesignerConfig	0.1.0+	核心配置接口
DesignerInstance	0.1.0+	实例方法
MaterialCategory	0.1.0+	素材分类
MaterialItem	0.1.0+	素材项
StyleListData	0.1.0+	分页数据

浏览器兼容性

所有 API 在支持的浏览器中都可正常使用：

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+

相关链接

• DesignerConfig 详细文档
• 实例方法详细文档
• 素材类型详细文档
• 事件系统详细文档

最佳实践

类型导入

使用 import type 导入类型（仅类型导入）：

// ✅ 推荐
import type { DesignerConfig } from 'ueditor-plus-designer'

// ❌ 不推荐
import { DesignerConfig } from 'ueditor-plus-designer'

类型注解

为函数参数和返回值添加类型注解：

const categoryLoader = async (): Promise<MaterialCategory[]> => {
  // 返回类型明确
  return []
}

const handleChange = (content: string): void => {
  // 参数类型明确
  console.log(content)
}

Null 检查

始终检查 ref 是否为 null：

// ✅ 推荐
if (designerRef.value) {
  const content = designerRef.value.getContent()
}

// 或使用可选链
const content = designerRef.value?.getContent()

// ❌ 不推荐（可能抛出错误）
const content = designerRef.value!.getContent()