# 5-2 [process] Tiptap Notion-Like 模板裁剪与 `leptos-tiptap` 映射分析 v1

> 更新时间：2026-04-19
>
> 这份文档已经按当前进展修正：
>
> 现在的问题不再是“这套模板能不能迁进来”，而是：
>
> **我们已经做出了一版 `leptos-tiptap` 编辑器，接下来应该从官方模板中保留什么行为模型，并优先把它接入主编辑器。**

## 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 数量当作当前阶段目标。**