lix-2026
1569699fbb
- 将不直接执行的 process-reference 文档迁入各域 reference 目录 - 更新 design/README、AGENTS 和总序文档，固定 process/draft/reference/done 目录语义 - 修正活跃文档中指向旧 process 位置的参考链接 验证：git diff --check；codegraph sync .
239 lines
7.9 KiB
Markdown
239 lines
7.9 KiB
Markdown
# 5-2 [reference] Tiptap Notion-Like 模板裁剪与 `leptos-tiptap` 映射分析 v1
|
|
|
|
> 更新时间：2026-04-19
|
|
>
|
|
> 当前状态：`reference`。本文只作为 tiptap / Notion-like 行为模型参考，不再作为当前执行 checklist；默认主编辑器已是页面内 `leptos-tiptap` island。
|
|
>
|
|
> 这份文档已经按当前进展修正：
|
|
>
|
|
> 现在的问题不再是“这套模板能不能迁进来”，而是：
|
|
>
|
|
> **默认主编辑器已经切到页面内 `leptos-tiptap` island；当前问题转为：应该从官方模板保留什么行为模型，并优先把哪些能力继续收口到当前主编辑器主链。**
|
|
|
|
## 1. 修正后的总判断
|
|
|
|
当前对官方模板的使用方式应当明确为：
|
|
|
|
1. 它是体验 benchmark，不是直接照搬对象。
|
|
2. 它是行为模型参考，不是 React 代码迁移目标。
|
|
3. 现阶段最值钱的不是再扩更多模板功能，而是把已实现能力接入主编辑器。
|
|
|
|
因此，这份模板的正确用途是：
|
|
|
|
> **借它定义“官方行为应当是什么”，再用 `leptos-tiptap` + Rust 把这些行为落到 `mnote` 的主链。**
|
|
|
|
## 2. 官方模板里当前最该保留的参考
|
|
|
|
### 2.1 主编辑器扩展组合
|
|
|
|
核心参考文件：
|
|
|
|
- `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-templates/notion-like/components/notion-like-editor.tsx`
|
|
|
|
当前值得保留的不是整份文件，而是这些决策：
|
|
|
|
- 以 Tiptap 正式 schema 组织常用块
|
|
- 常用块优先于低频复杂块
|
|
- `task list / task item` 使用正式扩展，不做 HTML 占位
|
|
- `UniqueID` 作为块身份辅助机制
|
|
- `Indent` 作为普通块缩进增强的参考扩展
|
|
|
|
### 2.2 slash 菜单行为模型
|
|
|
|
核心参考文件：
|
|
|
|
- `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-ui/slash-dropdown-menu/slash-dropdown-menu.tsx`
|
|
- `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-ui/slash-dropdown-menu/use-slash-dropdown-menu.ts`
|
|
|
|
当前最该保留的是：
|
|
|
|
- slash 入口就是块编辑器的主入口之一
|
|
- 菜单项的分组与命令组织方式
|
|
- 菜单锚点应跟随 caret，而不是随便找一个固定位置
|
|
|
|
### 2.3 浮动工具条行为模型
|
|
|
|
核心参考文件：
|
|
|
|
- `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-templates/notion-like/components/notion-like-editor-toolbar-floating.tsx`
|
|
|
|
当前最该保留的是：
|
|
|
|
- 工具条只在文本 selection 语境下出现
|
|
- 文本格式命令和 `turn into` 要分清语境
|
|
- 不要把固定显示工具条误当成“功能已完成”
|
|
|
|
### 2.4 左侧手柄与块菜单行为模型
|
|
|
|
核心参考文件：
|
|
|
|
- `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-ui/drag-context-menu/drag-context-menu.tsx`
|
|
|
|
当前最该保留的是：
|
|
|
|
- hover 先只显露手柄，不自动弹块菜单
|
|
- 块菜单应由左侧手柄点击触发
|
|
- `turn into / duplicate / delete / drag` 是块菜单的核心动作
|
|
|
|
这点非常关键，因为它直接影响我们后续对标 Wolai/Notion 的交互正确性。
|
|
|
|
## 3. 结合当前代码后的现实判断
|
|
|
|
### 3.1 已经有的东西
|
|
|
|
从当前实现看，下面这些已经不是“要不要做”，而是“如何迁进主链”：
|
|
|
|
- `paragraph / heading / list / todo / quote / code block / divider`
|
|
- slash 菜单
|
|
- 浮动工具条
|
|
- 左侧手柄
|
|
- 块菜单
|
|
- `turn into`
|
|
- 顶层拖拽
|
|
- refresh 后结构保留
|
|
|
|
对应当前实现入口：
|
|
|
|
- `/mnt/Data1T/mnote/rust/spikes/leptos-tiptap-spike/src/main.rs`
|
|
|
|
### 3.2 当前真正的缺口
|
|
|
|
当前真正的缺口不是模板 feature 数量，而是下面这些：
|
|
|
|
- 它还在 spike 里，不在主编辑器里
|
|
- 保存还没接上正式 Rust truth
|
|
- `block_id` 还没成为正式合同
|
|
- 页面引用 / 块引用还没打通
|
|
- 图片上传与附件桥还没接
|
|
- 表格还没做
|
|
|
|
所以现阶段不该继续把注意力平均分配到：
|
|
|
|
- Markdown 导入导出回归
|
|
- `kode` 组件分层整理
|
|
- 表格
|
|
- AI Cloud
|
|
- 协作链
|
|
|
|
## 4. `P0.5` 该如何采用官方模板
|
|
|
|
### 4.1 `P0.5` 要保留的部分
|
|
|
|
`P0.5` 应保留的不是一堆零散 feature，而是以下几类“官方行为”：
|
|
|
|
- 主编辑器使用正式 Tiptap 扩展，而不是临时 HTML 拼接
|
|
- slash 菜单锚定 caret
|
|
- 选中文字才出现浮动工具条
|
|
- hover 只显手柄，点击手柄才弹块菜单
|
|
- `turn into` 作为块菜单和工具条共享的一组块类型切换动作
|
|
- `UniqueID` 作为 runtime 辅助，但最终块 id 仍归 Rust
|
|
|
|
### 4.2 `P0.5` 不要再继续扩的部分
|
|
|
|
`P0.5` 不应该继续向下扩这些模板能力：
|
|
|
|
- 协作
|
|
- AI
|
|
- TOC
|
|
- 完整表格
|
|
- 图片上传整链
|
|
- 移动端全量工具条
|
|
|
|
原因很简单：
|
|
|
|
这些都不会帮助我们更快完成“接入主编辑器”。
|
|
|
|
## 5. 官方模板到 `mnote` 的映射口径
|
|
|
|
### 5.1 直接借行为，不借代码
|
|
|
|
以下部分应当“借行为模型”，不应当尝试直接照搬 React 代码：
|
|
|
|
- `slash-dropdown-menu`
|
|
- `drag-context-menu`
|
|
- `notion-like-editor-toolbar-floating`
|
|
|
|
原因：
|
|
|
|
- React hooks / context / portal 不能直接进入 Leptos
|
|
- 真正有价值的是交互时机、状态边界、动作分组
|
|
- 不是 `tsx` 组件本身
|
|
|
|
### 5.2 `block id` 需要现在就纳入主线
|
|
|
|
官方模板里的 `UniqueID.configure(...)` 很重要，但口径要修正成：
|
|
|
|
- 官方参考：
|
|
`/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-templates/notion-like/components/notion-like-editor.tsx`
|
|
- Rust 真相字段：
|
|
`/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/model.rs`
|
|
|
|
最终原则：
|
|
|
|
1. Rust `EditorBlock.block_id` 是持久化真相。
|
|
2. Tiptap `UniqueID` 只负责浏览器 runtime 内的节点身份辅助。
|
|
3. 不允许把前端临时 id 倒灌成正式文档真相。
|
|
|
|
### 5.3 `Indent` 值得做，但不在这一轮前排
|
|
|
|
官方缩进扩展很值得参考：
|
|
|
|
- `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-extension/indent-extension.ts`
|
|
|
|
但当前它不应排在主编辑器接入之前。
|
|
|
|
更合理的顺序是：
|
|
|
|
1. 先完成主编辑器接入
|
|
2. 再完成 Rust 保存边界
|
|
3. 再考虑普通块缩进增强
|
|
|
|
### 5.4 图片上传与表格都先后置
|
|
|
|
官方模板确实有图片与表格能力，但现在不应让它们进入主 checklist 前排。
|
|
|
|
原因：
|
|
|
|
- 图片上传不是当前切流主编辑器的阻塞项
|
|
- 表格更不是当前高频刚需
|
|
- 两者都容易把工作重新带到复杂 UI / 服务桥接细节
|
|
|
|
## 6. 哪些旧 checklist 应从主线降级
|
|
|
|
下面这些项不删，但不应继续放在当前主线前排：
|
|
|
|
- Markdown 导入导出回归
|
|
参考 `blocks` 仍然有价值，但它更像切流后的回归与兼容工作。
|
|
|
|
- 借 `kode` 做 Leptos 组件分层
|
|
这个参考可以保留，但它属于实现注记，不是当前交付里程碑。
|
|
|
|
- 完整表格
|
|
继续后置。
|
|
|
|
- 完整图片上传
|
|
继续后置，只保留后续最小桥接预留。
|
|
|
|
## 7. 对接下来工作的直接建议
|
|
|
|
基于当前代码和官方模板，接下来最合理的顺序是：
|
|
|
|
1. 先把当前 `leptos-tiptap` 编辑器接入主编辑器。
|
|
2. 同时建立正式的 Rust load/save 边界。
|
|
3. 在这个过程中引入稳定 block id 策略。
|
|
4. 等它真正成为主编辑器后，再规划 `P1 / P1.5` 的 Wolai 对标体验增强。
|
|
|
|
这也意味着：
|
|
|
|
当前官方模板对我们的最大价值，不是再提供更多可抄的 feature，而是帮助我们定义：
|
|
|
|
- 哪些交互已经够了
|
|
- 哪些交互时机必须修正
|
|
- 哪些功能现在根本不该做
|
|
|
|
## 8. 最终结论
|
|
|
|
当前对这份模板的正确使用方式是：
|
|
|
|
> **以后续主编辑器开发继续以 Tiptap 官方能力模型为体验上限，以 `leptos-tiptap` 为运行时接入层；先完成主编辑器接入和 Rust truth 落地，再单独规划 Wolai 对标增强，不再把模板 feature 数量当作当前阶段目标。**
|