# neweditor

**Repository Path**: xzq_95/neweditor

## Basic Information

- **Project Name**: neweditor
- **Description**: 这是富文本编辑器的仓库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-28
- **Last Updated**: 2026-02-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TestFox RichText Editor

基于 TipTap 的富文本编辑器，专为 TestFox 项目设计，支持完整的主题系统和亮色/暗色模式切换。

## 特性

- ✅ 完整的富文本编辑功能
- ✅ 支持 40+ 种编程语言语法高亮
- ✅ Slash Command（斜杠命令）快捷操作
- ✅ 图片粘贴上传（Ctrl+V）
- ✅ 文件拖拽上传（图片、视频、音频）
- ✅ 自动上传到服务器（支持自定义上传处理器）
- ✅ 拖拽排序功能
- ✅ 表格编辑（合并单元格、调整列宽等）
- ✅ 多语言支持（中文/英文）
- ✅ 主题系统（亮色/暗色模式）
- ✅ 响应式设计

## 安装

```bash
npm install neweditor
# 或
pnpm install neweditor
# 或
yarn add neweditor
```

## 使用

### 基础使用

```vue
<template>
  <RichTextEditor :editor="editor" locale="zh-CN" />
</template>

<script setup>
import { useEditor, RichTextEditor, allExtensions } from 'neweditor'
import 'neweditor/dist/style.css'

const editor = useEditor({
  extensions: allExtensions,
  content: '<p>Hello World!</p>',
})
</script>
```

### 完整示例

```vue
<template>
  <div class="editor-wrapper">
    <RichTextEditor 
      :editor="editor" 
      locale="zh-CN"
      class="my-editor"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { useEditor, RichTextEditor, allExtensions } from 'neweditor'
import 'neweditor/dist/style.css'

const content = ref('<p>初始内容</p>')

const editor = useEditor({
  extensions: allExtensions,
  content: content.value,
  editable: true,
  autofocus: false,
  editorProps: {
    attributes: {
      'data-placeholder': '请输入内容...',
    },
  },
  onUpdate: ({ editor }) => {
    content.value = editor.getHTML()
  },
  onFocus: ({ editor }) => {
    console.log('编辑器获得焦点')
  },
  onBlur: ({ editor }) => {
    console.log('编辑器失去焦点')
  },
})
</script>

<style>
.editor-wrapper {
  border: 1px solid #d9d9d9;
  border-radius: 4px;
}
</style>
```

### 带文件上传功能的示例

```vue
<template>
  <div class="editor-wrapper">
    <RichTextEditor 
      :editor="editor" 
      locale="zh-CN"
      class="my-editor"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { useEditor, RichTextEditor, allExtensions } from 'testfox-richtext-editor'
import 'testfox-richtext-editor/dist/style.css'

const content = ref('<p>初始内容</p>')

// 自定义文件上传处理器
const handleFileUpload = async (file) => {
  try {
    // 1. 验证文件大小（例如限制 100MB）
    const maxSize = 100 * 1024 * 1024
    if (file.size > maxSize) {
      console.error('文件大小不能超过100MB')
      return null
    }

    // 2. 创建 FormData
    const formData = new FormData()
    formData.append('file', file)

    // 3. 调用你的上传 API
    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData,
    })

    const result = await response.json()

    // 4. 返回文件 URL（成功）或 null（失败）
    if (result.success) {
      return result.fileUrl  // 返回文件的访问 URL
    } else {
      console.error('上传失败:', result.message)
      return null
    }
  } catch (error) {
    console.error('上传异常:', error)
    return null
  }
}

// 配置扩展并传递上传处理器
const configuredExtensions = allExtensions.map(ext => {
  // 为图片、视频、音频扩展配置上传处理器
  if (ext.name === 'image' || ext.name === 'video' || ext.name === 'audio') {
    return ext.configure({
      uploadHandler: handleFileUpload
    })
  }
  return ext
})

const editor = useEditor({
  extensions: configuredExtensions,  // 使用配置好的扩展
  content: content.value,
  editable: true,
  onUpdate: ({ editor }) => {
    content.value = editor.getHTML()
  },
})
</script>

<style>
.editor-wrapper {
  border: 1px solid #d9d9d9;
  border-radius: 4px;
}
</style>
```

## API

### useEditor(options)

创建编辑器实例的 Hook。

**参数：**

```typescript
interface EditorOptions {
  extensions: Extension[]      // 扩展列表
  content?: string             // 初始内容（HTML）
  editable?: boolean           // 是否可编辑
  autofocus?: boolean          // 是否自动聚焦
  editorProps?: EditorProps    // 编辑器属性
  onUpdate?: (props) => void   // 内容更新回调
  onFocus?: (props) => void    // 获得焦点回调
  onBlur?: (props) => void     // 失去焦点回调
  onCreate?: (props) => void   // 创建完成回调
}
```

**返回值：**

返回一个响应式的编辑器实例。

### 文件上传配置

#### uploadHandler

文件上传处理器函数，用于处理图片、视频、音频的上传。

**类型签名：**

```typescript
type UploadHandler = (file: File) => Promise<string | null>
```

**参数：**
- `file`: File 对象，包含要上传的文件

**返回值：**
- 成功：返回文件的访问 URL（字符串）
- 失败：返回 `null`

**配置方式：**

```javascript
// 为需要上传功能的扩展配置 uploadHandler
const configuredExtensions = allExtensions.map(ext => {
  if (ext.name === 'image' || ext.name === 'video' || ext.name === 'audio') {
    return ext.configure({
      uploadHandler: async (file) => {
        // 你的上传逻辑
        const url = await uploadToServer(file)
        return url  // 返回 URL 或 null
      }
    })
  }
  return ext
})
```

**工作流程：**

1. 用户粘贴图片或拖拽文件到编辑器
2. 编辑器创建临时预览（Blob URL）
3. 立即显示预览，用户无需等待
4. 后台调用 `uploadHandler` 上传文件
5. 上传成功后，自动替换为真实 URL
6. 上传失败则删除临时预览

**示例实现：**

```javascript
const handleFileUpload = async (file) => {
  try {
    // 验证文件大小
    const maxSize = 100 * 1024 * 1024  // 100MB
    if (file.size > maxSize) {
      console.error('文件过大')
      return null
    }

    // 上传到服务器
    const formData = new FormData()
    formData.append('file', file)

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

    const result = await response.json()

    // 返回文件 URL
    return result.success ? result.fileUrl : null
  } catch (error) {
    console.error('上传失败:', error)
    return null
  }
}
```

### RichTextEditor 组件

编辑器 UI 组件。

**Props：**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `editor` | Editor | - | 编辑器实例（必需） |
| `locale` | String | `'zh-CN'` | 语言设置（zh-CN/en） |

### allExtensions

包含所有内置扩展的数组，包括：

- 文本格式化（粗体、斜体、下划线、删除线等）
- 标题（H1-H6）
- 列表（有序、无序、任务列表）
- 代码（行内代码、代码块）
- 表格
- 图片、视频、音频
- 链接
- 引用块
- 分栏布局
- 折叠面板
- Slash Command
- 拖拽排序
- 搜索和替换
- 等等...

## 编辑器功能

### 文本格式化
- 粗体、斜体、下划线、删除线、上标、下标
- 标题（H1-H6）
- 文本颜色和背景色
- 字体大小
- 文本对齐
- 清除格式
- 格式刷

### 列表和引用
- 无序列表
- 有序列表
- 任务列表
- 引用块
- 缩进

### 代码
- 行内代码
- 代码块（支持 40+ 种语言语法高亮）

### 媒体内容
- 图片（支持粘贴、拖拽上传、调整大小）
- 视频（支持拖拽上传）
- 音频（支持拖拽上传）
- iframe

### 表格
- 创建表格
- 添加/删除行和列
- 合并/拆分单元格
- 调整列宽
- 表格拖拽排序

### 快捷功能
- Slash Command（输入 `/` 或 `、` 触发）
- 拖拽排序
- 搜索和替换
- 撤销/重做
- 字符统计

## 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Ctrl/Cmd + B` | 粗体 |
| `Ctrl/Cmd + I` | 斜体 |
| `Ctrl/Cmd + U` | 下划线 |
| `Ctrl/Cmd + Shift + X` | 删除线 |
| `Ctrl/Cmd + E` | 行内代码 |
| `Ctrl/Cmd + Z` | 撤销 |
| `Ctrl/Cmd + Shift + Z` | 重做 |
| `Ctrl/Cmd + K` | 插入链接 |
| `Ctrl/Cmd + V` | 粘贴图片 |
| `/` 或 `、` | Slash Command |
| `Tab` | 增加缩进 |
| `Shift + Tab` | 减少缩进 |

## 主题系统

编辑器支持亮色和暗色两种主题模式，通过 CSS 变量控制。

### 主题变量

```css
/* 亮色主题 */
.theme-light .testfox-rich-text-editor {
  --editor-primary-color: #9373ee;
  --editor-text-color: rgba(0, 0, 0, 0.85);
  --editor-background-color: #ffffff;
  --editor-border-color: #f0f0f0;
  /* ... 更多变量 */
}

/* 暗色主题 */
.theme-dark .testfox-rich-text-editor {
  --editor-primary-color: #9373ee;
  --editor-text-color: rgba(255, 255, 255, 0.85);
  --editor-background-color: #1f1f1f;
  --editor-border-color: #303030;
  /* ... 更多变量 */
}
```

### 自定义主题

可以通过覆盖 CSS 变量来自定义主题：

```css
.my-editor {
  --editor-primary-color: #your-color;
  --editor-background-color: #your-bg;
}
```

## 开发

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
npm run dev
```

### 构建

```bash
npm run build
```

### 类型检查

```bash
npm run typecheck
```

## 扩展开发

如需为编辑器添加新功能，可以创建自定义扩展。详细的扩展开发指南请参考：

- [扩展开发文档](./docs/extension.md)
- [Slash Command 指南](./docs/slash-command-guide.md)
- [Slash Command 示例](./docs/slash-command-examples.md)

## 文件上传功能

### 功能特性

编辑器支持以下文件上传方式：

- ✅ **图片粘贴上传**：按 `Ctrl+V` 粘贴图片，自动上传
- ✅ **图片拖拽上传**：拖拽图片文件到编辑器
- ✅ **视频拖拽上传**：拖拽视频文件到编辑器
- ✅ **音频拖拽上传**：拖拽音频文件到编辑器
- ✅ **即时预览**：上传前立即显示预览
- ✅ **自动替换**：上传成功后自动替换为真实 URL
- ✅ **失败处理**：上传失败自动删除预览

### 支持的文件类型

| 类型 | 扩展名 | 操作方式 |
|------|--------|---------|
| 图片 | jpg, jpeg, png, gif, webp, svg, bmp | 粘贴、拖拽 |
| 视频 | mp4, webm, ogg | 拖拽 |
| 音频 | mp3, wav, ogg | 拖拽 |

### 实现步骤

#### 1. 定义上传处理器

```javascript
const handleFileUpload = async (file) => {
  try {
    // 验证文件大小
    const maxSize = 100 * 1024 * 1024  // 100MB
    if (file.size > maxSize) {
      console.error('文件大小不能超过100MB')
      return null
    }

    // 创建 FormData
    const formData = new FormData()
    formData.append('file', file)

    // 调用上传 API
    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData,
    })

    const result = await response.json()

    // 返回文件 URL（成功）或 null（失败）
    if (result.success) {
      return result.fileUrl
    } else {
      console.error('上传失败:', result.message)
      return null
    }
  } catch (error) {
    console.error('上传异常:', error)
    return null
  }
}
```

#### 2. 配置扩展

```javascript
import { allExtensions } from 'testfox-richtext-editor'

// 为需要上传功能的扩展配置 uploadHandler
const configuredExtensions = allExtensions.map(ext => {
  if (ext.name === 'image' || ext.name === 'video' || ext.name === 'audio') {
    return ext.configure({
      uploadHandler: handleFileUpload
    })
  }
  return ext
})
```

#### 3. 创建编辑器

```javascript
const editor = useEditor({
  extensions: configuredExtensions,  // 使用配置好的扩展
  content: '<p>Hello World!</p>',
})
```

### 完整示例

```vue
<template>
  <RichTextEditor :editor="editor" locale="zh-CN" />
</template>

<script setup>
import { useEditor, RichTextEditor, allExtensions } from 'testfox-richtext-editor'
import 'testfox-richtext-editor/dist/style.css'

// 上传处理器
const handleFileUpload = async (file) => {
  try {
    const maxSize = 100 * 1024 * 1024
    if (file.size > maxSize) {
      alert('文件大小不能超过100MB')
      return null
    }

    const formData = new FormData()
    formData.append('file', file)

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

    const result = await response.json()
    return result.success ? result.fileUrl : null
  } catch (error) {
    console.error('上传失败:', error)
    return null
  }
}

// 配置扩展
const configuredExtensions = allExtensions.map(ext => {
  if (ext.name === 'image' || ext.name === 'video' || ext.name === 'audio') {
    return ext.configure({ uploadHandler: handleFileUpload })
  }
  return ext
})

// 创建编辑器
const editor = useEditor({
  extensions: configuredExtensions,
  content: '<p>试试粘贴图片或拖拽文件到这里...</p>',
})
</script>
```

### 上传流程

```
1. 用户粘贴图片或拖拽文件
   ↓
2. 创建临时预览（Blob URL）
   ↓
3. 立即显示预览（用户无需等待）
   ↓
4. 后台调用 uploadHandler 上传
   ↓
5. 上传成功
   ├─ 替换为真实 URL
   └─ 释放临时 Blob URL
   ↓
6. 上传失败
   ├─ 删除临时预览
   └─ 释放临时 Blob URL
```

### 注意事项

1. **返回值约定**
   - 成功：必须返回文件的完整访问 URL（字符串）
   - 失败：必须返回 `null`

2. **文件大小限制**
   - 建议在前端验证文件大小
   - 避免上传超大文件导致失败

3. **错误处理**
   - 捕获所有异常并返回 `null`
   - 提供友好的错误提示

4. **URL 格式**
   - 返回的 URL 必须是可访问的完整 URL
   - 例如：`https://example.com/uploads/image.jpg`

5. **异步处理**
   - uploadHandler 必须是异步函数
   - 使用 `async/await` 或返回 Promise

### 常见问题

**Q: 粘贴后图片消失了？**

A: 检查 uploadHandler 是否返回了正确的 URL。如果返回 `null`，图片会被删除。

**Q: 如何禁用上传功能？**

A: 不配置 uploadHandler 即可。图片会保持为 Blob URL（仅本地预览）。

**Q: 支持哪些文件类型？**

A: 图片（粘贴+拖拽）、视频（拖拽）、音频（拖拽）。可以通过扩展支持更多类型。

**Q: 如何自定义文件大小限制？**

A: 在 uploadHandler 中添加验证逻辑：

```javascript
const maxSize = 50 * 1024 * 1024  // 50MB
if (file.size > maxSize) {
  alert('文件过大')
  return null
}
```

**Q: 如何添加上传进度提示？**

A: 在 uploadHandler 中使用 UI 库显示进度：

```javascript
const handleFileUpload = async (file) => {
  // 显示加载提示
  showLoading('正在上传...')
  
  try {
    const url = await uploadToServer(file)
    hideLoading()
    return url
  } catch (error) {
    hideLoading()
    showError('上传失败')
    return null
  }
}
```

## 浏览器兼容性

- Chrome/Edge: ✅ 完全支持
- Firefox: ✅ 完全支持
- Safari: ✅ 完全支持
- IE: ❌ 不支持

## 相关链接

- [Gitee 仓库](https://gitee.com/xzq_95/testfox-richtext-editor)
- [TipTap 官方文档](https://tiptap.dev/)

## 许可证

GPL-3.0

## 贡献

欢迎提交 Issue 和 Pull Request！