适配版本：HarmonyOS 5.0.0 或以上
阅读目标：掌握如何同步富文本段落的顺序结构，实现软删除机制、插入位置控制，以及多设备间协同时冲突排序的处理逻辑

---

🧠 一、为什么需要段落顺序同步？

场景	问题
A 设备插入了一个新段在第 2 段后，B 设备却显示在末尾	顺序不同步
B 删除了第 3 段，A 设备还在展示	删除未同步
多人同时插入段落后顺序错乱	缺少排序规则

---

📦 二、段落顺序结构设计（维护段落列表）

type BlockOrderList = string[]  // blockId 列表，按顺序排列

// 存储 key: note_order_${noteId}

📌 和段落内容分开维护，保证插入、删除操作对内容无侵扰。

---

📝 三、写入顺序列表（每次编辑同步）

function updateBlockOrder(noteId: string, orderList: string[]) {
  kvStore.put(`note_order_${noteId}`, JSON.stringify(orderList))
}

📌 插入新段落 → 在 orderList 中插入对应 blockId
📌 删除段落 → 从 orderList 中移除对应 blockId

---

🧹 四、软删除机制设计（安全删除）

为什么不直接删除段落？

• 保留撤销/回滚能力

• 避免跨设备异步误删

• 可显示“此段已被删除”提示（更友好）

block.deleted = true

UI 上显示为灰色块 + “此段已被删除”

---

删除逻辑：

function deleteBlock(blockId: string) {
  const block = localBlocksMap[blockId]
  block.deleted = true
  block.timestamp = Date.now()
  updateBlock(block)

  const orderList = getOrderList()
  updateBlockOrder(currentNoteId, orderList.filter(id => id !== blockId))
}

---

🔁 五、段落渲染顺序控制（按列表渲染）

const orderList = getKV(`note_order_${noteId}`)
const blocks = orderList
  .map(id => localBlocksMap[id])
  .filter(b => !b?.deleted)

📌 保证：只展示未删除内容、顺序完全一致、UI 刷新精确

---

👥 六、多设备协同排序冲突处理策略

冲突情况：

• A 插入 block1 → 第2段后

• B 同时插入 block2 → 第2段后

• → 结果：顺序不一致

---

解决方案：插入排序算法 + 时间戳优先

function insertBlockAfter(refId: string, newBlockId: string) {
  const index = orderList.indexOf(refId)
  if (index !== -1) {
    orderList.splice(index + 1, 0, newBlockId)
    updateBlockOrder(currentNoteId, orderList)
  }
}

多人冲突时按 newBlock.timestamp 进行二次排序保障一致性

---

🎨 七、段落 ID 命名建议

block.id = `${deviceId}_${timestamp}`

📌 保证唯一性 + 可读性 + 用于排序冲突决策辅助

---

✅ 八、小结

能力模块	实现说明
段落顺序列表结构	独立 note_order_${noteId} 存储段落 ID 排序
插入/删除同步机制	插入修改顺序列表，删除设置 block.deleted = true
渲染器按顺序展示段落	所有段落按 orderList 顺序 + 过滤 deleted 渲染
协同冲突排序策略	使用插入点位置 + 时间戳排序解决多人同步时插入顺序问题

---

📘 下一篇预告

第6篇｜富文本笔记结构管理：多笔记本支持 + 文件夹/标签分类 + 收藏与归档机制设计