gzkx-editor 0.0.0

package/STARTUP.md

@@ -0,0 +1,535 @@
+# ProseMirror 开发环境启动指南
+
+## 目录
+
+- [项目简介](#项目简介)
+- [环境要求](#环境要求)
+- [项目结构](#项目结构)
+- [首次设置](#首次设置)
+- [常用命令详解](#常用命令详解)
+- [开发工作流程](#开发工作流程)
+- [测试](#测试)
+- [CSS 文件说明](#css-文件说明)
+- [故障排除](#故障排除)
+
+---
+
+## 项目简介
+
+ProseMirror 是一个基于 `contentEditable` 的语义化富文本编辑器，支持协作编辑和自定义文档 Schema。
+
+本仓库是 ProseMirror 的中央仓库（monorepo），用于管理所有核心模块的开发和问题追踪。各核心模块以 Git 子模块的形式存在。
+
+**官方资源：**
+- 官网：https://prosemirror.net
+- 问题追踪：https://code.haverbeke.berlin/prosemirror/prosemirror/issues
+- 论坛：https://discuss.prosemirror.net
+
+---
+
+## 环境要求
+
+- **Node.js**：建议 v18 或更高版本
+- **npm**：随 Node.js 自动安装
+- **Git**：用于管理子模块
+- **操作系统**：macOS、Linux、Windows 均可
+
+验证环境：
+
+```bash
+node --version   # 应显示 v18.x.x 或更高
+npm --version    # 应显示 9.x.x 或更高
+git --version    # 应显示 2.x.x 或更高
+```
+
+---
+
+## 项目结构
+
+```
+prosemirror/
+├── bin/
+│   └── pm.js          # 开发工具主脚本
+├── demo/              # Demo 页面
+│   ├── index.html     # Demo 主页
+│   ├── demo.ts        # Demo 入口
+│   └── ...
+├── model/             # 文档数据模型
+├── transform/        # 文档转换操作
+├── state/             # 编辑器状态管理
+├── view/              # 视图渲染层
+├── keymap/            # 键盘快捷键绑定
+├── inputrules/        # 输入规则
+├── history/           # 撤销/重做
+├── collab/            # 协作编辑
+├── commands/          # 编辑命令
+├── gapcursor/          # 空隙光标
+├── schema-basic/      # 基础文档 Schema
+├── schema-list/       # 列表 Schema
+├── menu/              # 菜单栏
+├── example-setup/     # 示例配置
+├── markdown/          # Markdown 解析
+├── dropcursor/        # 拖拽光标
+├── search/            # 搜索功能
+├── test-builder/      # 测试构建工具
+├── changeset/         # 变更集
+└── website/          # 官网
+```
+
+---
+
+## 首次设置
+
+### 步骤 1：克隆仓库
+
+如果你从 Git 克隆了本仓库，跳过此步。如果是从其他来源获取的，确保仓库完整。
+
+### 步骤 2：安装子模块
+
+ProseMirror 的核心模块以 Git 子模块形式存在，需要单独克隆：
+
+```bash
+node bin/pm.js install
+```
+
+此命令会：
+1. 克隆所有子模块到对应目录
+2. 安装根目录依赖
+3. 安装各子模块依赖
+4. 构建所有模块
+
+**如果安装过程出错**，可以分步执行：
+
+```bash
+# 1. 先手动克隆所有子模块
+cd D:/work/prosemirror
+for submodule in model transform state view keymap inputrules history collab commands gapcursor schema-basic schema-list menu example-setup markdown dropcursor test-builder changeset search website; do
+  git clone https://code.haverbeke.berlin/prosemirror/prosemirror-$submodule.git $submodule
+done
+
+# 2. 安装根目录依赖
+npm install
+
+# 3. 构建所有模块
+node bin/pm.js build
+```
+
+### 步骤 3：处理 CSS 文件（仅 Windows）
+
+**问题原因：**
+- `demo/index.html` 中引用了 `parent/view/style/prosemirror.css` 等路径
+- `parent` 本应是符号链接指向父目录，但 Windows 符号链接需要管理员权限
+- 如果未正确设置，CSS 样式将无法加载
+
+**解决方案：复制 CSS 文件**
+
+```bash
+# 创建 CSS 目标目录
+mkdir -p demo/view/style demo/menu/style demo/example-setup/style demo/gapcursor/style demo/search/style
+
+# 复制 CSS 文件
+cp view/style/*.css demo/view/style/
+cp menu/style/*.css demo/menu/style/
+cp example-setup/style/*.css demo/example-setup/style/
+cp gapcursor/style/*.css demo/gapcursor/style/
+cp search/style/*.css demo/search/style/
+
+# 修改 index.html 中的路径
+# 将 parent/view/style/prosemirror.css 改为 view/style/prosemirror.css
+# （如果 index.html 尚未修改）
+```
+
+**同时需要修改 `index.html`**（如果未修改的话）：
+
+将：
+```html
+<link rel=stylesheet href="parent/view/style/prosemirror.css">
+<link rel=stylesheet href="parent/menu/style/menu.css">
+<link rel=stylesheet href="parent/example-setup/style/style.css">
+<link rel=stylesheet href="parent/gapcursor/style/gapcursor.css">
+```
+
+改为：
+```html
+<link rel=stylesheet href="view/style/prosemirror.css">
+<link rel=stylesheet href="menu/style/menu.css">
+<link rel=stylesheet href="example-setup/style/style.css">
+<link rel=stylesheet href="gapcursor/style/gapcursor.css">
+```
+
+---
+
+## 常用命令详解
+
+### 启动开发服务器
+
+```bash
+node bin/pm.js dev-start
+```
+
+- 启动 HTTP 服务器监听 8080 端口
+- 启动文件监视器，自动重建发生变化的模块
+- 访问地址：http://127.0.0.1:8080/demo/
+
+**重要**：修改代码后会自动重新构建，刷新浏览器即可看到更新。
+
+---
+
+### 停止开发服务器
+
+```bash
+node bin/pm.js dev-stop
+```
+
+---
+
+### 构建所有模块
+
+```bash
+node bin/pm.js build
+```
+
+手动触发所有模块的 TypeScript 编译和打包。不启动服务器，不监视文件变化。
+
+---
+
+### 监视文件变化
+
+```bash
+node bin/pm.js watch
+```
+
+与 `dev-start` 类似，但只监视和重建，不启动 HTTP 服务器。
+
+---
+
+### 运行测试
+
+```bash
+# 运行所有测试（默认使用 Chrome 浏览器）
+node bin/pm.js test
+
+# 使用 Firefox 浏览器
+node bin/pm.js test --firefox
+
+# 跳过浏览器测试
+node bin/pm.js test --no-browser
+
+# 只运行包含特定关键词的测试
+node bin/pm.js test --grep "undo"
+```
+
+---
+
+### 查看子模块状态
+
+```bash
+node bin/pm.js status
+```
+
+显示所有子模块的 Git 状态，包括未提交的更改、未推送的提交等。
+
+---
+
+### 提交更改
+
+```bash
+node bin/pm.js commit -m "你的提交信息"
+```
+
+自动在所有有更改的子模块中执行 Git 提交。
+
+---
+
+### 推送更改
+
+```bash
+node bin/pm.js push
+```
+
+将所有子模块中已提交但未推送的更改推送到远程仓库。
+
+---
+
+### 搜索代码
+
+```bash
+node bin/pm.js grep "关键词"
+```
+
+在所有子模块的源代码中搜索指定的正则表达式模式。
+
+---
+
+### 查看模块列表
+
+```bash
+# 列出所有模块
+node bin/pm.js modules
+
+# 只列出核心模块
+node bin/pm.js modules --core
+```
+
+---
+
+## 开发工作流程
+
+### 日常开发
+
+1. **启动开发服务器**
+   ```bash
+   node bin/pm.js dev-start
+   ```
+
+2. **访问 Demo 页面**
+   打开浏览器访问：http://127.0.0.1:8080/demo/
+
+3. **修改代码**
+   - 修改各子模块的 TypeScript 源文件
+   - 保存后自动重建
+   - 刷新浏览器查看效果
+
+4. **停止服务器**
+   ```bash
+   node bin/pm.js dev-stop
+   ```
+
+### 修改特定模块
+
+假设要修改 `view` 模块：
+
+1. 找到对应的源文件，如 `view/src/view.ts`
+2. 修改代码并保存
+3. 如果开发服务器在运行，会自动重建
+4. 刷新浏览器查看效果
+
+### 提交更改
+
+```bash
+# 1. 查看哪些模块有更改
+node bin/pm.js status
+
+# 2. 提交所有更改
+node bin/pm.js commit -m "描述你的更改"
+
+# 3. 推送到远程
+node bin/pm.js push
+```
+
+---
+
+## 测试
+
+### 运行测试套件
+
+```bash
+node bin/pm.js test
+```
+
+这会运行所有子模块中的非浏览器测试和浏览器测试。
+
+### 测试文件位置
+
+各模块的测试文件位于 `test/` 目录下，使用 `@marijn/testtool` 测试框架。
+
+### 单独运行某个模块的测试
+
+```bash
+cd <模块目录>
+# 依赖 test-builder 工具运行测试
+```
+
+---
+
+## CSS 文件说明
+
+### 为什么需要单独处理 CSS？
+
+1. `demo/index.html` 引用了 CSS 文件：
+   - `parent/view/style/prosemirror.css`
+   - `parent/menu/style/menu.css`
+   - 等...
+
+2. `parent` 原本是指向父目录的符号链接，使路径 `parent/view` 等价于项目根目录的 `view`。
+
+3. 在 Linux/macOS 上这没有问题，但在 Windows 上：
+   - 创建符号链接需要管理员权限
+   - 或者需要启用"开发者模式"
+   - 如果没有权限，符号链接无法正常工作
+
+4. 解决方案是直接将 CSS 文件复制到 `demo/` 下的对应目录中。
+
+### 需要复制的 CSS 文件
+
+| 模块 | CSS 文件 | 目标目录 |
+|------|----------|----------|
+| view | prosemirror.css | demo/view/style/ |
+| menu | menu.css | demo/menu/style/ |
+| example-setup | style.css | demo/example-setup/style/ |
+| gapcursor | gapcursor.css | demo/gapcursor/style/ |
+| search | search.css | demo/search/style/ |
+
+---
+
+## 故障排除
+
+### 问题：子模块目录不存在
+
+**错误信息：**
+```
+module `view` is missing. Did you forget to run `pm install`?
+```
+
+**解决方案：**
+```bash
+node bin/pm.js install
+```
+
+如果 install 命令中的 npm 执行失败，手动执行：
+```bash
+npm install
+node bin/pm.js build
+```
+
+---
+
+### 问题：CSS 样式不生效
+
+**症状：** 页面加载后没有样式或样式错乱。
+
+**检查：**
+1. 确认 CSS 文件已复制到 `demo/` 下的对应目录
+2. 确认 `demo/index.html` 中的 CSS 路径正确
+3. 确认 `demo/view/style/prosemirror.css` 等文件存在
+
+**解决方案（重新复制 CSS）：**
+```bash
+rm -rf demo/view demo/menu demo/example-setup demo/gapcursor demo/search
+mkdir -p demo/view/style demo/menu/style demo/example-setup/style demo/gapcursor/style demo/search/style
+cp view/style/*.css demo/view/style/
+cp menu/style/*.css demo/menu/style/
+cp example-setup/style/*.css demo/example-setup/style/
+cp gapcursor/style/*.css demo/gapcursor/style/
+cp search/style/*.css demo/search/style/
+```
+
+---
+
+### 问题：端口 8080 被占用
+
+**错误信息：**
+```
+Error: listen EADDRINUSE 127.0.0.1:8080
+```
+
+**解决方案：**
+1. 停止占用 8080 端口的进程：
+   ```bash
+   # Windows
+   netstat -ano | findstr :8080
+   taskkill /PID <PID号> /F
+
+   # macOS/Linux
+   lsof -i :8080
+   kill -9 <PID>
+   ```
+
+2. 或使用环境变量指定其他端口：
+   ```bash
+   PORT=9090 node bin/pm.js dev-start
+   ```
+
+---
+
+### 问题：npm 命令找不到
+
+**错误信息：**
+```
+Error: spawnSync npm ENOENT
+```
+
+**解决方案：**
+1. 确认 Node.js 和 npm 已正确安装：
+   ```bash
+   node --version
+   npm --version
+   ```
+
+2. 如果 npm 不在 PATH 中，尝试：
+   ```bash
+   # Windows: 使用完整路径
+   C:\Program Files\nodejs\npm.cmd install
+
+   # 或者先进入 Node.js 安装目录
+   cd C:\Program Files\nodejs
+   .\npm.cmd install
+   ```
+
+3. 或者先手动安装依赖：
+   ```bash
+   npm install
+   node bin/pm.js build
+   ```
+
+---
+
+### 问题：构建失败
+
+**解决方案：**
+1. 清理并重新构建：
+   ```bash
+   rm -rf node_modules
+   npm install
+   node bin/pm.js build
+   ```
+
+2. 检查是否有 TypeScript 错误：
+   ```bash
+   node bin/pm.js build
+   ```
+   查看错误输出信息。
+
+---
+
+### 问题：dev-stop 无法停止服务器
+
+**症状：** 运行 `dev-stop` 后服务器仍在运行。
+
+**解决方案：**
+```bash
+# 手动杀死进程
+# Windows
+netstat -ano | findstr :8080
+taskkill /PID <PID> /F
+
+# 或者通过 PID 文件查找
+cat bin/.pm-dev.pid
+taskkill /PID <PID> /F
+```
+
+---
+
+## 附录：子模块简介
+
+| 模块 | 说明 |
+|------|------|
+| `model` | ProseMirror 文档的数据模型定义 |
+| `transform` | 文档的转换操作（如删除、插入、替换） |
+| `state` | 编辑器的完整状态（包括文档、选择、事务） |
+| `view` | 视图层，负责将状态渲染为 DOM |
+| `keymap` | 键盘快捷键绑定 |
+| `inputrules` | 输入规则（如自动补全、转换） |
+| `history` | 历史记录管理（撤销/重做） |
+| `collab` | 协作编辑支持 |
+| `commands` | 编辑命令（如加粗、斜体） |
+| `gapcursor` | 空隙光标显示 |
+| `schema-basic` | 基础文档 Schema（段落、标题、引用等） |
+| `schema-list` | 列表 Schema（有序列表、无序列表） |
+| `menu` | 菜单栏组件 |
+| `example-setup` | 示例配置和完整编辑器构建 |
+| `markdown` | Markdown 格式解析 |
+| `dropcursor` | 拖拽时的光标样式 |
+| `search` | 搜索和替换功能 |
+| `test-builder` | 测试构建工具 |
+| `changeset` | 变更集实现 |