kc-plate-editor 0.5.4 → 0.5.6

package/README.md

@@ -8,7 +8,34 @@
 
 | 版本 | 状态 | 说明 |
 |------|------|------|
-| v0.5.0 | ✅ 已发布私服 | 当前稳定版本 |
+| v0.5.6 | ✅ 最新版本 | 增强上传配置灵活性 |
+| v0.5.5 | ✅ 稳定版本 | 快捷键保存、本地存储、目录跳转优化 |
+| v0.5.4 | ✅ 稳定版本 | 滚动和布局优化 |
+| v0.5.0 | ✅ 已发布私服 | 基础稳定版本 |
+
+### v0.5.6 更新内容
+
+- **增强上传配置** - 新增 `UploadConfig` 详细配置接口
+- **增强 AI 配置** - 新增 `AIConfig` 详细配置接口
+- **自定义上传函数** - 支持 `customUpload` 完全自定义上传逻辑
+- **自定义 AI 函数** - 支持 `customCopilot` 和 `customCommand` 自定义 AI 逻辑
+- **文件验证** - 支持 `maxSize` 和 `acceptTypes` 文件验证
+- **额外表单数据** - 支持 `extraData` 添加额外表单字段
+- **灵活响应解析** - 支持多种服务端响应格式
+- **配置辅助函数** - 新增 `getUploadConfig`、`getAiConfig` 等辅助函数
+
+### v0.5.5 更新内容
+
+- **快捷键保存** - 支持 `Ctrl+S` / `Cmd+S` 快捷键保存
+- **本地存储** - 新增 `saveToLocalStorage()` 和 `clearLocalStorage()` 方法
+- **目录跳转优化** - 修复目录点击跳转不准确的问题
+- **onSave 回调** - 新增 `onSave` 属性用于处理快捷键保存事件
+
+### v0.5.4 更新内容
+
+- 修复编辑器容器双滚动条问题
+- 优化 `EditorContainer` 的 `demo` 变体高度设置
+- 修复工具栏吸顶在嵌套滚动容器中失效的问题
 
 ### v0.5.0 更新内容
 
@@ -25,6 +52,7 @@
 - [特性](#特性)
 - [安装](#安装)
 - [快速开始](#快速开始)
+- [集成注意事项](#集成注意事项) ⭐ **重要**
 - [工具栏配置](#工具栏配置)
 - [内容操作](#内容操作)
 - [导出功能](#导出功能)
@@ -171,6 +199,437 @@ function App() {
 }
 ```
 
+### 6. 高级上传配置 (v0.5.6+)
+
+```tsx
+import { ConfigProvider, PlateEditor, type UploadConfig } from 'kc-plate-editor';
+
+// 详细的上传配置
+const uploadConfig: UploadConfig = {
+  url: '/api/upload',           // 上传地址
+  fieldName: 'file',            // 文件字段名
+  maxSize: 10 * 1024 * 1024,    // 最大 10MB
+  acceptTypes: ['image/*', 'video/*', 'application/pdf'],
+  headers: {
+    'X-Upload-Token': 'your-token',
+  },
+  extraData: {
+    category: 'document',
+    source: 'editor',
+  },
+};
+
+function App() {
+  return (
+    <ConfigProvider
+      config={{
+        baseURL: 'https://api.example.com',  // API 基础地址
+        upload: uploadConfig,
+        locale: 'zh-CN',
+      }}
+    >
+      <PlateEditor />
+    </ConfigProvider>
+  );
+}
+```
+
+### 7. 自定义上传函数
+
+```tsx
+import { ConfigProvider, PlateEditor, type UploadResult } from 'kc-plate-editor';
+
+// 完全自定义上传逻辑
+async function customUpload(
+  file: File, 
+  onProgress?: (progress: number) => void
+): Promise<UploadResult> {
+  const formData = new FormData();
+  formData.append('file', file);
+  
+  // 使用你自己的上传逻辑
+  const response = await fetch('/api/my-upload', {
+    method: 'POST',
+    body: formData,
+  });
+  
+  const result = await response.json();
+  
+  return {
+    url: result.fileUrl,
+    name: file.name,
+    size: file.size,
+    type: file.type,
+    key: result.fileId,
+  };
+}
+
+function App() {
+  return (
+    <ConfigProvider
+      config={{
+        upload: {
+          customUpload,  // 使用自定义上传函数
+        },
+        locale: 'zh-CN',
+      }}
+    >
+      <PlateEditor />
+    </ConfigProvider>
+  );
+}
+```
+
+### 8. AI 配置 (v0.5.6+)
+
+```tsx
+import { ConfigProvider, PlateEditor, type AIConfig } from 'kc-plate-editor';
+
+// 详细的 AI 配置
+const aiConfig: AIConfig = {
+  copilotUrl: '/api/ai/copilot',    // Copilot 自动补全 API
+  commandUrl: '/api/ai/command',    // AI 命令/对话 API
+  apiKey: 'your-api-key',           // API 密钥
+  model: 'gpt-4',                   // 模型名称
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+};
+
+function App() {
+  return (
+    <ConfigProvider
+      config={{
+        baseURL: 'https://api.example.com',
+        ai: aiConfig,
+        locale: 'zh-CN',
+      }}
+    >
+      <PlateEditor />
+    </ConfigProvider>
+  );
+}
+```
+
+---
+
+## 集成注意事项
+
+> ⚠️ **重要**: 在将 kc-plate-editor 集成到现有项目时，请仔细阅读以下注意事项，避免常见问题。
+
+### 1. 全局样式冲突
+
+**问题**: 项目中的全局 CSS 可能会影响编辑器的显示效果。
+
+**常见冲突**:
+
+```css
+/* ❌ 这些全局样式会破坏编辑器的列表显示 */
+ul, ol {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+/* ❌ 这会影响编辑器内的链接样式 */
+a {
+  text-decoration: none;
+  color: inherit;
+}
+```
+
+**解决方案**:
+
+```css
+/* ✅ 方案1: 使用更具体的选择器，排除编辑器区域 */
+ul:not([data-slate-node]), ol:not([data-slate-node]) {
+  list-style: none;
+}
+
+/* ✅ 方案2: 在编辑器容器内重置样式 */
+[data-plate-editor-container] ul,
+[data-plate-editor-container] ol {
+  list-style: revert;
+  padding: revert;
+  margin: revert;
+}
+
+/* ✅ 方案3: 直接注释掉全局样式（推荐） */
+/* ul, ol { list-style: none; } */
+```
+
+### 2. 容器高度和滚动
+
+**问题**: 编辑器需要明确的高度才能正确滚动。
+
+```tsx
+// ❌ 错误：没有设置高度，编辑器会无限增长
+<div>
+  <PlateEditor />
+</div>
+
+// ✅ 正确：设置固定高度或使用 flex 布局
+<div style={{ height: 500 }}>
+  <PlateEditor />
+</div>
+
+// ✅ 正确：使用 flex 布局填充可用空间
+<div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+  <header>...</header>
+  <div style={{ flex: 1, overflow: 'hidden' }}>
+    <PlateEditor />
+  </div>
+</div>
+```
+
+**Ant Design Card 中使用**:
+
+```tsx
+// ✅ 推荐配置：设置 body 的高度和 overflow
+<Card 
+  style={{ minHeight: 500 }} 
+  styles={{ 
+    body: { 
+      padding: 0, 
+      height: 500, 
+      display: 'flex', 
+      flexDirection: 'column',
+      overflow: 'hidden'  // 防止双滚动条
+    } 
+  }}
+>
+  <PlateEditor />
+</Card>
+```
+
+### 3. 工具栏吸顶
+
+**问题**: 工具栏吸顶需要正确的滚动容器。
+
+```tsx
+// ❌ 错误：外层容器有 overflow: auto，会创建新的滚动上下文
+<div style={{ overflow: 'auto', height: 500 }}>
+  <PlateEditor toolbarSticky={true} />
+</div>
+
+// ✅ 正确：外层容器使用 overflow: hidden
+<div style={{ overflow: 'hidden', height: 500 }}>
+  <PlateEditor toolbarSticky={true} />
+</div>
+```
+
+**独立工具栏场景**:
+
+```tsx
+// 使用 StandaloneToolbar 时，需要自己管理滚动容器
+import { StandaloneToolbar, PlateEditor } from 'kc-plate-editor';
+
+// 滚动容器
+<div className="scroll-container" style={{ overflow: 'auto', height: 500 }}>
+  {/* 工具栏使用 CSS sticky */}
+  <div style={{ position: 'sticky', top: 0, zIndex: 50 }}>
+    <StandaloneToolbar config={config} editor={editor} sticky={false} />
+  </div>
+  
+  <PlateEditor showToolbar={false} />
+</div>
+```
+
+### 4. 快捷键保存
+
+**v0.5.5 新增**: 支持 `Ctrl+S` / `Cmd+S` 快捷键保存。
+
+```tsx
+<PlateEditor
+  // 方式1: 使用 onSave 回调处理保存逻辑
+  onSave={(content) => {
+    console.log('快捷键保存:', content);
+    // 调用 API 保存到服务器
+    saveToServer(content);
+  }}
+  
+  // 方式2: 启用自动保存到 localStorage
+  autoSave={true}
+  autoSaveKey="my-editor-content"
+  autoSaveInterval={5000}  // 5秒自动保存一次
+/>
+```
+
+**清理本地存储**:
+
+```tsx
+// 发布或退出时清理临时数据
+const handlePublish = async () => {
+  await publishDocument();
+  editorRef.current?.clearLocalStorage();
+};
+
+const handleExit = () => {
+  editorRef.current?.clearLocalStorage();
+  navigate('/');
+};
+```
+
+### 5. 目录跳转
+
+**问题**: 目录点击跳转不到正确位置。
+
+**原因**: 编辑器使用了嵌套滚动容器，`scrollIntoView` 可能无法正确工作。
+
+**v0.5.5 已修复**: 目录跳转现在会自动查找正确的滚动容器。
+
+```tsx
+// 如果仍有问题，确保编辑器容器结构正确
+<div style={{ height: 500, overflow: 'hidden' }}>
+  <PlateEditor 
+    showToc={true}
+    tocPosition="right"
+    tocWidth={240}
+  />
+</div>
+```
+
+### 6. 表单集成
+
+**在 Ant Design Form 中使用**:
+
+```tsx
+import { Form, Input, Button } from 'antd';
+import { PlateEditor, ConfigProvider, EditorErrorBoundary } from 'kc-plate-editor';
+
+function ArticleForm() {
+  const editorRef = useRef<PlateEditorRef>(null);
+  
+  const handleSubmit = async () => {
+    const content = editorRef.current?.getContent();
+    const markdown = editorRef.current?.getMarkdown();
+    const html = await editorRef.current?.getHtml();
+    
+    // 提交到服务器
+    await submitArticle({ content, markdown, html });
+  };
+
+  return (
+    <Form onFinish={handleSubmit}>
+      <Form.Item label="标题" name="title">
+        <Input />
+      </Form.Item>
+      
+      <Form.Item label="内容">
+        {/* 添加边框样式 */}
+        <div style={{ border: '1px solid #d9d9d9', borderRadius: 8, overflow: 'hidden' }}>
+          <ConfigProvider config={{ locale: 'zh-CN' }}>
+            <EditorErrorBoundary>
+              <PlateEditor
+                ref={editorRef}
+                toolbarConfig={BASIC_TOOLBAR}
+                toolbarSticky={false}  // 表单中不需要吸顶
+                showSettings={false}
+              />
+            </EditorErrorBoundary>
+          </ConfigProvider>
+        </div>
+      </Form.Item>
+      
+      <Button type="primary" htmlType="submit">提交</Button>
+    </Form>
+  );
+}
+```
+
+### 7. 全屏编辑模式
+
+**实现全屏沉浸式编辑**:
+
+```tsx
+function FullScreenEditor() {
+  return (
+    <div style={{ 
+      height: '100vh', 
+      display: 'flex', 
+      flexDirection: 'column',
+      background: '#fff',
+    }}>
+      {/* 顶部导航栏 */}
+      <div style={{ 
+        padding: '8px 16px', 
+        borderBottom: '1px solid #e8e8e8',
+        flexShrink: 0,
+      }}>
+        <span>文档标题</span>
+        <Button onClick={handleSave}>保存</Button>
+      </div>
+      
+      {/* 编辑器区域 - flex: 1 填充剩余空间 */}
+      <div style={{ flex: 1, overflow: 'hidden' }}>
+        <PlateEditor
+          toolbarConfig={FULL_TOOLBAR}
+          toolbarSticky={true}
+          toolbarAlign="center"
+          contentMaxWidth={900}
+          showToc={true}
+          tocPosition="right"
+          autoFocus
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### 8. 错误边界
+
+**始终使用 EditorErrorBoundary 包裹编辑器**:
+
+```tsx
+import { EditorErrorBoundary, PlateEditor } from 'kc-plate-editor';
+
+// ✅ 推荐：使用错误边界防止编辑器崩溃影响整个页面
+<EditorErrorBoundary>
+  <PlateEditor />
+</EditorErrorBoundary>
+```
+
+### 9. 性能优化
+
+**避免不必要的重渲染**:
+
+```tsx
+// ❌ 错误：每次渲染都创建新的配置对象
+<PlateEditor
+  toolbarConfig={{ ...FULL_TOOLBAR, history: false }}
+/>
+
+// ✅ 正确：使用 useMemo 缓存配置
+const toolbarConfig = useMemo(() => ({
+  ...FULL_TOOLBAR,
+  history: false,
+}), []);
+
+<PlateEditor toolbarConfig={toolbarConfig} />
+```
+
+**预设切换时重新挂载编辑器**:
+
+```tsx
+// 使用 key 强制重新挂载，确保工具栏配置正确应用
+<PlateEditor
+  key={`editor-${activePreset}`}
+  toolbarConfig={getToolbarConfig()}
+/>
+```
+
+### 10. 常见问题排查
+
+| 问题 | 可能原因 | 解决方案 |
+|------|----------|----------|
+| 列表没有项目符号 | 全局 CSS 重置了 list-style | 移除或修改全局样式 |
+| 双滚动条 | 容器和编辑器都有 overflow | 外层使用 `overflow: hidden` |
+| 工具栏不吸顶 | 滚动容器不正确 | 检查父容器的 overflow 设置 |
+| 目录跳转失效 | 嵌套滚动容器 | 升级到 v0.5.5 |
+| 快捷键无效 | 焦点不在编辑器 | 确保编辑器已聚焦 |
+| 内容丢失 | 未保存就离开 | 使用 autoSave 或 onSave |
+
 ---
 
 ## 工具栏配置
@@ -345,49 +804,158 @@ const outline = editorRef.current?.getOutline();
 
 ### PlateEditorRef 方法
 
+#### 内容管理
+
 | 方法 | 说明 | 返回值 |
 |------|------|--------|
 | `getContent()` | 获取编辑器内容 | `Value` |
 | `setContent(value)` | 设置编辑器内容 | `void` |
 | `resetContent()` | 重置为初始内容 | `void` |
+| `getText()` | 获取纯文本内容 | `string` |
+| `isEmpty()` | 检查编辑器是否为空 | `boolean` |
+
+#### Markdown/HTML 转换
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
 | `getMarkdown()` | 获取 Markdown | `string` |
 | `setMarkdown(md)` | 设置 Markdown | `void` |
 | `insertMarkdown(md)` | 插入 Markdown | `void` |
 | `getHtml()` | 获取 HTML | `Promise<string>` |
 | `setHtml(html)` | 设置 HTML | `void` |
+
+#### 查找替换
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
 | `find(text, options)` | 查找文本 | `MatchPosition[]` |
 | `replace(search, replace, options)` | 替换文本 | `number` |
+
+#### 文档分析
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
 | `getWordCount()` | 获取字数统计 | `WordCountResult` |
 | `getOutline()` | 获取文档大纲 | `OutlineItem[]` |
+
+#### 导出功能
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
 | `exportAsHtml(filename)` | 导出 HTML | `Promise<void>` |
 | `exportAsMarkdown(filename)` | 导出 Markdown | `Promise<void>` |
 | `exportAsPdf(filename)` | 导出 PDF | `Promise<void>` |
 | `exportAsImage(filename)` | 导出图片 | `Promise<void>` |
+
+#### 插入操作
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
 | `insertText(text)` | 插入文本 | `void` |
 | `insertLink(url, text)` | 插入链接 | `void` |
 | `insertImage(url)` | 插入图片 | `void` |
+
+#### 格式控制
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
 | `toggleMark(mark)` | 切换格式 | `void` |
 | `undo()` | 撤销 | `void` |
 | `redo()` | 重做 | `void` |
+
+#### 编辑器控制
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
 | `focus()` | 聚焦编辑器 | `void` |
 | `blur()` | 失焦编辑器 | `void` |
 | `getEditor()` | 获取底层编辑器实例 | `TPlateEditor` |
 
+#### 修改状态
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `isModified()` | 检查内容是否已修改 | `boolean` |
+| `resetModifiedState()` | 重置修改状态 | `void` |
+
+#### 工具栏/目录控制
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `setToolbarVisible(visible)` | 设置工具栏可见性 | `void` |
+| `setTocVisible(visible)` | 设置目录可见性 | `void` |
+
+#### 本地存储 (v0.5.5+)
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `saveToLocalStorage()` | 手动保存到 localStorage | `void` |
+| `clearLocalStorage()` | 清理 localStorage 临时数据 | `void` |
+
+#### 自动保存
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `getAutoSaveState()` | 获取自动保存状态 | `AutoSaveState` |
+| `saveNow()` | 立即触发保存 | `void` |
+| `restoreAutoSave()` | 恢复自动保存的内容 | `Value \| null` |
+| `clearAutoSave()` | 清除自动保存数据 | `void` |
+
 ### PlateEditorProps
 
+#### 基础属性
+
 | 属性 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `value` | `Value` | - | 编辑器内容 |
 | `onChange` | `(value: Value) => void` | - | 内容变化回调 |
 | `mode` | `'edit' \| 'view' \| 'suggestion'` | `'edit'` | 编辑器模式 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readOnly` | `boolean` | `false` | 是否只读 |
+| `autoFocus` | `boolean` | `false` | 是否自动聚焦 |
+| `className` | `string` | - | 自定义类名 |
+
+#### 工具栏属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
 | `toolbarConfig` | `ToolbarConfig` | `FULL_TOOLBAR` | 工具栏配置 |
 | `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
+| `toolbarSticky` | `boolean` | `true` | 工具栏是否吸顶 |
 | `toolbarAlign` | `'left' \| 'center' \| 'right'` | `'left'` | 工具栏对齐 |
 | `toolbarFullWidth` | `boolean` | `false` | 工具栏是否全宽 |
+| `toolbarClassName` | `string` | - | 工具栏类名 |
+| `toolbarStyle` | `CSSProperties` | - | 工具栏样式 |
+| `customToolbarButtons` | `CustomToolbarButtons` | - | 自定义工具栏按钮 |
+
+#### 目录属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
 | `showToc` | `boolean` | `false` | 是否显示目录 |
-| `tocPosition` | `'left' \| 'right'` | `'left'` | 目录位置 |
-| `autoFocus` | `boolean` | `false` | 是否自动聚焦 |
-| `placeholder` | `string` | - | 占位符文本 |
+| `tocPosition` | `'left' \| 'right' \| 'top' \| 'custom'` | `'left'` | 目录位置 |
+| `tocWidth` | `string \| number` | `'320px'` | 目录宽度 |
+| `tocClassName` | `string` | - | 目录类名 |
+| `tocStyle` | `CSSProperties` | - | 目录样式 |
+| `renderToc` | `(toc: ReactNode) => ReactNode` | - | 自定义目录渲染 |
+
+#### 保存属性 (v0.5.5+)
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `onSave` | `(content: Value) => void` | - | 快捷键保存回调 |
+| `autoSave` | `boolean` | `false` | 是否启用自动保存 |
+| `autoSaveKey` | `string` | - | localStorage 存储键名 |
+| `autoSaveInterval` | `number` | `30000` | 自动保存间隔（毫秒） |
+| `onAutoSave` | `(content: Value) => void` | - | 自动保存回调 |
+
+#### 其他属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `showSettings` | `boolean` | `true` | 是否显示设置按钮 |
+| `contentMaxWidth` | `string \| number` | - | 内容区域最大宽度 |
+| `onModifiedChange` | `(isModified: boolean) => void` | - | 修改状态变化回调 |
 
 ---
 

package/dist/components/editor/plate-editor.d.ts

@@ -88,6 +88,8 @@ export interface PlateEditorProps {
     autoSaveInterval?: number;
     /** 自动保存回调 */
     onAutoSave?: (content: Value) => void;
+    /** 保存回调（用于快捷键保存 Ctrl+S / Cmd+S） */
+    onSave?: (content: Value) => void;
 }
 /**
  * PlateEditor 组件引用接口
@@ -150,8 +152,12 @@ export interface PlateEditorRef {
     exportAsMarkdown: (filename?: string) => Promise<void>;
     /** 导出为 PDF 文件 */
     exportAsPdf: (filename?: string) => Promise<void>;
-    /** 导出为图片文件 */
-    exportAsImage: (filename?: string) => Promise<void>;
+    /** 导出为图片 */
+    exportAsImage: (filename: string) => Promise<void>;
+    /** 清理本地存储的临时内容 */
+    clearLocalStorage: () => void;
+    /** 手动保存到本地存储 */
+    saveToLocalStorage: () => void;
     /** 查找文本 */
     find: (searchText: string, options?: FindOptions) => MatchPosition[];
     /** 替换文本 */