mirror of
https://github.com/Tencent/tmagic-editor.git
synced 2026-07-06 14:17:52 +00:00
0f42989ca3
将 pageSteps/codeBlockState/dataSourceState 三套独立历史栈收敛为统一的 steps 结构 （按 stepType 分桶），并新增 registerStepType/setStepName/getStepName 支持自定义 扩展历史类型。同步重构 history 相关服务、组件、工具方法、测试与文档。
123 lines
4.3 KiB
Markdown
123 lines
4.3 KiB
Markdown
# historyService事件
|
||
|
||
## change
|
||
|
||
- **详情：** 页面历史记录发生变化（`page` 类型 `push` / `undo` / `redo` 成功时触发；与 `code-block-history-change` / `data-source-history-change` 同构）
|
||
|
||
- **事件回调函数：** `(pageId: Id, step: StepValue) => void`
|
||
|
||
::: details 查看 StepValue 及关联类型定义
|
||
<<< @/../packages/editor/src/type.ts#StepValue{ts}
|
||
|
||
<<< @/../packages/editor/src/type.ts#BaseStepValue{ts}
|
||
|
||
<<< @/../packages/editor/src/type.ts#StepExtra{ts}
|
||
|
||
<<< @/../packages/editor/src/type.ts#HistoryOpType{ts}
|
||
|
||
<<< @/../packages/editor/src/type.ts#HistoryOpSource{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#Id{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#MNode{ts}
|
||
:::
|
||
|
||
:::tip
|
||
回调签名已与其它历史类型统一为 `(id, step)`。当游标处于历史栈边界（已无法继续撤销 / 重做）时 `undo` / `redo` 返回 `null`，此时不会触发该事件。
|
||
:::
|
||
|
||
## marker-change
|
||
|
||
- **详情：** 通过 [`setMarker`](./historyServiceMethods.md#setmarker) 为某个历史栈种入 `initial` 基线时触发（适用于所有类型）
|
||
|
||
- **事件回调函数：** `(id: Id, marker: StepValue, stepType: HistoryStepType) => void`
|
||
|
||
## clear
|
||
|
||
- **详情：** 调用 [`clear`](./historyServiceMethods.md#clear) 清空历史栈时触发（适用于所有类型）
|
||
|
||
- **事件回调函数：** `(id: Id | undefined, stepType: HistoryStepType) => void`
|
||
|
||
:::tip
|
||
`id` 缺省（清空 `stepType` 下全部栈）时回调的 `id` 为 `undefined`。
|
||
:::
|
||
|
||
## code-block-history-change
|
||
|
||
- **详情：** 代码块历史记录发生变化（`push('codeBlock', step, codeBlockId)` / `undo('codeBlock', id)` / `redo('codeBlock', id)` 成功时触发）
|
||
|
||
- **事件回调函数：** `(codeBlockId: Id, step: CodeBlockStepValue) => void`
|
||
|
||
::: details 查看 CodeBlockStepValue 及关联类型定义
|
||
<<< @/../packages/editor/src/type.ts#CodeBlockStepValue{ts}
|
||
|
||
<<< @/../packages/editor/src/type.ts#BaseStepValue{ts}
|
||
|
||
<<< @/../packages/editor/src/type.ts#HistoryOpSource{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#CodeBlockContent{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#Id{ts}
|
||
:::
|
||
|
||
:::tip
|
||
- 新增触发的 step 其 diff 项 `oldSchema` 为 `null`
|
||
- 删除触发的 step 其 diff 项 `newSchema` 为 `null`
|
||
- `undo` / `redo` 返回 `null`（边界状态）时不会触发该事件
|
||
:::
|
||
|
||
## data-source-history-change
|
||
|
||
- **详情：** 数据源历史记录发生变化（`push('dataSource', step, dataSourceId)` / `undo('dataSource', id)` / `redo('dataSource', id)` 成功时触发）
|
||
|
||
- **事件回调函数：** `(dataSourceId: Id, step: DataSourceStepValue) => void`
|
||
|
||
::: details 查看 DataSourceStepValue 及关联类型定义
|
||
<<< @/../packages/editor/src/type.ts#DataSourceStepValue{ts}
|
||
|
||
<<< @/../packages/editor/src/type.ts#BaseStepValue{ts}
|
||
|
||
<<< @/../packages/editor/src/type.ts#HistoryOpSource{ts}
|
||
|
||
<<< @/../packages/schema/src/index.ts#Id{ts}
|
||
:::
|
||
|
||
:::tip
|
||
- 新增触发的 step 其 diff 项 `oldSchema` 为 `null`
|
||
- 删除触发的 step 其 diff 项 `newSchema` 为 `null`
|
||
- `undo` / `redo` 返回 `null`（边界状态）时不会触发该事件
|
||
:::
|
||
|
||
## mark-saved
|
||
|
||
- **详情：** 调用 [`markSaved`](./historyServiceMethods.md#marksaved) 标记「已保存」记录时触发
|
||
|
||
- **事件回调函数：** `(payload: { kind: 'all' | HistoryStepType; id?: Id }) => void`
|
||
|
||
::: tip
|
||
- `markSaved(stepType)`（缺省 id）触发时 `kind` 为 `all`，无 `id`（此时 `stepType` 不生效）
|
||
- `markSaved(stepType, id)` 触发时 `kind` 为对应的 `stepType`（`page` / `codeBlock` / `dataSource` / 扩展），`id` 为目标栈 id
|
||
:::
|
||
|
||
## save-to-indexed-db
|
||
|
||
- **详情：** `saveToIndexedDB` 把历史记录写入本地 IndexedDB 成功时触发
|
||
|
||
- **事件回调函数：** `(snapshot: PersistedHistoryState) => void`
|
||
|
||
::: details 查看 PersistedHistoryState 类型定义
|
||
<<< @/../packages/editor/src/type.ts#PersistedHistoryState{ts}
|
||
|
||
<<< @/../packages/editor/src/utils/undo-redo.ts#SerializedUndoRedo{ts}
|
||
:::
|
||
|
||
## restore-from-indexed-db
|
||
|
||
- **详情：** `restoreFromIndexedDB` 从本地 IndexedDB 读取并重建历史记录成功时触发（找不到记录时不触发）
|
||
|
||
- **事件回调函数：** `(snapshot: PersistedHistoryState) => void`
|
||
|
||
::: details 查看 PersistedHistoryState 类型定义
|
||
<<< @/../packages/editor/src/type.ts#PersistedHistoryState{ts}
|
||
:::
|