# sceditor

**Repository Path**: chenlong_sd/sceditor

## Basic Information

- **Project Name**: sceditor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 简易富文本编辑器

一个不依赖第三方库的轻量富文本编辑器，基于原生 `contenteditable` 实现，当前重点增强了粘贴还原、文件卡片、源码/Markdown 辅助编辑、草稿恢复和编辑区内提示交互。

## 文档导航
- `README.md`：项目概览与快速开始。
- `docs/FEATURES.md`：当前已具备功能清单与能力边界。
- `docs/USAGE.md`：使用文档、初始化方式、模式说明、常见操作。
- `docs/EXEC_COMMAND_MIGRATION.md`：逐步去除 `execCommand` 的迁移方案。
- `docs/ROADMAP.md`：通用编辑器方向的分阶段开发计划。

## 文件结构
- `index.html`：页面入口，挂载编辑器容器并引入资源。
- `editor.css`：编辑器样式。
- `editor.js`：发布用单文件产物，平时不直接维护。
- `editor.min.js`：发布用单文件压缩产物（由 `terser` 生成）。
- `src/core/SimpleRichEditor.js`：核心类、基础渲染与事件绑定。
- `src/modules/`：按功能拆分的扩展模块，如面板、Slash 命令、图片、表格、上传、输出与 Markdown 转换等。
- `scripts/build-editor.js`：在最终发布前将 `src/` 打包为单文件 `editor.js`。
- `scripts/minify-editor.js`：将 `editor.js` 压缩为 `editor.min.js`。
- `scripts/run-tests.js`：用本机 Chrome / Edge headless 自动打开 `tests.html` 并输出回归结果。
- `package.json`：本地构建与测试脚本入口。
- `docs/`：功能、使用、迁移与路线图文档。

## 快速开始
1. 保持 `index.html`、`editor.css` 与 `src/` 目录结构完整。
2. 直接用浏览器打开 `index.html`。
3. 默认会创建 `window.editorInstance`，可在控制台直接调用实例方法。
4. 日常开发直接修改 `src/` 并刷新页面即可；只有需要单文件产物时再执行打包。

## 当前重点能力
- 富文本基础编辑：标题、段落、加粗、斜体、下划线、删除线、对齐、缩进、列表。
- 结构化内容块：Todo、引用块、代码块、分割线、表格、图片、文件卡片。
- 文件资源面板：集中查看当前编辑区内的附件与下载链接，支持快速定位与打开。
- 附件联动：支持在资源面板中直接替换或删除附件，并同步更新编辑区。
- 粘贴增强：HTML / 纯文本 / 文件粘贴，带清洗、归一化、脏 HTML 异常兜底与调试回放能力。
- 多模式编辑：常规模式、HTML 源码模式、Markdown 辅助编辑模式。
- 本地草稿：自动保存、刷新后编辑区内恢复提示。
- 服务端草稿同步：可通过 `draftSync.load/save/clear` 接入远端草稿拉取、保存和清理，默认按最新时间在本地 / 云端草稿间选优；当前批注元数据已内嵌在 `html` 中，随草稿一起远程保存。
- 版本历史：支持自动快照与手动保存当前版本，可在面板中查看、恢复和删除历史版本。
- 批注：支持对选区添加批注、定位正文、标记已解决、删除；正文定位锚点保留在 `mark[data-comment-id]` 上，批注元数据默认存于隐藏的 `div.editor-comment-storage[data-comment-storage]` 节点中。
- 查找替换：支持工具栏、`/` 快捷命令、`Ctrl/Cmd + F`，覆盖富文本 / 源码 / Markdown 模式。
- 编辑器内提示：已将草稿恢复与清空确认改成编辑区内提示，不再依赖浏览器原生弹窗。
- 长文优化：高频编辑事件的状态刷新会按帧合并，附件面板关闭时不会做无谓的全量扫描。
- 移动端适配：窄屏下工具栏改为横向滑动并保持吸顶，链接 / 颜色 / 附件面板会切换为贴边浮层。
- 无障碍增强：工具栏、编辑区、查找面板、源码/Markdown 输出区补齐 ARIA 语义，状态按钮同步 `aria-pressed` / `aria-expanded` / `aria-hidden`，键盘焦点更清晰。
- 基础事件接口：已支持 `onChange`、`onFocus`、`onBlur`。

## 初始化示例
```js
window.editorInstance = new SimpleRichEditor('#app', {
  placeholder: '请输入内容...',
  initialHTML: '<p>这是一个由 JavaScript 初始化的简易富文本编辑器。</p>',
  layout: {
    width: 'min(1100px, 100%)',
    height: 560,
    padding: 20,
    toolbarControlHeight: 36,
  },
  enablePasteDebug: false,
  enableDraftAutosave: true,
  draftAutosaveDelay: 800,
  draftRestorePrompt: true,
  onChange: ({ html, mode, source }) => {
    console.log('change', mode, source, html);
  },
  onFocus: ({ mode, source }) => {
    console.log('focus', mode, source);
  },
  onBlur: ({ mode, source }) => {
    console.log('blur', mode, source);
  },
}).init();
```

## 常用配置
- `placeholder`：编辑区占位提示。
- `initialHTML`：初始化内容。
- `enablePasteDebug`：是否开启粘贴调试面板。
- `enableDraftAutosave`：是否开启本地草稿自动保存。
- `draftAutosaveDelay`：草稿自动保存延迟，单位毫秒。
- `draftRestorePrompt`：是否启用草稿恢复提示；当前 UI 为编辑区内提示条。
- `draftStorageKey`：自定义草稿存储键，便于多实例隔离。
- `draftSync`：可选的服务端草稿同步配置，支持 `load` / `save` / `clear` 与 `prefer`（`newer` / `remote` / `local`）；推荐直接保存整份 `html`，这样批注会自动随草稿一起远程存储。
- `layout`：基础尺寸配置，支持 `width`、`height`、`padding`、`toolbarControlHeight`；`height` 为整个编辑器总高度。
- `versionHistory`：版本历史配置，支持 `enabled`、`maxEntries`、`autoSnapshot`、`autoSnapshotInterval`。
- `comments`：批注配置，支持 `enabled`、`authorName`、`load`、`save`。
- `comments.load/save`：仅在你需要单独读写批注数组时再接入；如果已经接了 `draftSync`，通常不必额外拆分批注远端存储。
- `onImageUpload(file)`：自定义图片上传，返回最终 URL。
- `onFileUpload(file)`：自定义文件上传，返回最终 URL。
- `onChange(payload)`：内容实际变更后的回调。
- `onFocus(payload)`：编辑区或源码/Markdown 编辑区获得焦点时回调。
- `onBlur(payload)`：编辑区或源码/Markdown 编辑区失焦时回调。
- `onCommentChange(payload)`：批注增删、解决/重开时回调。

## 构建与测试
- 单文件打包：`npm run build` 或 `npm run bundle`
- 自动化回归：`npm run test`
- 仅运行浏览器测试：`npm run test:browser`
- 也可直接执行：`node scripts/build-editor.js`、`node scripts/run-tests.js`
- `npm run test` 直接以 `src/` 源码作为入口，通过本机 Chrome / Edge headless 打开 `tests.html`。
- 若浏览器不在常见安装路径，可通过环境变量 `SCEDITOR_TEST_BROWSER` 指定可执行文件路径。
- 日常维护以 `src/` 为源码入口，`editor.js` 只在最终交付或发布时生成。

## 开发说明
- 当前版本仍存在部分 `document.execCommand` 依赖，详见 `docs/EXEC_COMMAND_MIGRATION.md`。
- 后续通用编辑器开发计划见 `docs/ROADMAP.md`。

## 适用场景
- 后台 CMS 内容编辑。
- 文章、公告、通知、知识库内容录入。
- 带图片、文件、表格的富文本输入。
- 需要调试网页粘贴还原结果的本地场景。

## 已知边界
- 仍是轻量编辑器，不适合复杂协同编辑。
- 复杂网页样式会经过清洗与归一化，不保证 100% 原样保留。
- Markdown 目前更偏“辅助编辑与导入导出能力”，不是完全独立的数据模型。