@tmagic/editor 1.8.0-beta.4 → 1.8.0-beta.6

package/src/utils/indexed-db.ts

@@ -0,0 +1,122 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * 一组极简的、基于原生 IndexedDB 的 Promise KV 工具，避免引入额外依赖。
+ * 仅用于浏览器环境；在不支持 IndexedDB 的环境（如 SSR / 部分测试环境）下会 reject。
+ */
+
+/** 是否处于支持 IndexedDB 的环境。 */
+export const isIndexedDBSupported = (): boolean => typeof indexedDB !== 'undefined' && indexedDB !== null;
+
+/**
+ * 打开（必要时升级）数据库，确保目标 objectStore 存在后返回连接。
+ *
+ * 由于 objectStore 只能在 `onupgradeneeded` 内创建，这里先以当前版本打开，
+ * 若发现 store 不存在则关闭连接、以更高版本重开来按需创建，兼容动态 storeName。
+ */
+export const openIndexedDB = (dbName: string, storeName: string): Promise<IDBDatabase> =>
+  new Promise((resolve, reject) => {
+    if (!isIndexedDBSupported()) {
+      reject(new Error('当前环境不支持 IndexedDB'));
+      return;
+    }
+
+    const request = indexedDB.open(dbName);
+
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(storeName)) {
+        db.createObjectStore(storeName);
+      }
+    };
+
+    request.onerror = () => reject(request.error);
+
+    request.onsuccess = () => {
+      const db = request.result;
+      if (db.objectStoreNames.contains(storeName)) {
+        resolve(db);
+        return;
+      }
+
+      // store 不存在：以更高版本重开，在 onupgradeneeded 中创建。
+      const nextVersion = db.version + 1;
+      db.close();
+      const upgradeRequest = indexedDB.open(dbName, nextVersion);
+      upgradeRequest.onupgradeneeded = () => {
+        const upgradeDb = upgradeRequest.result;
+        if (!upgradeDb.objectStoreNames.contains(storeName)) {
+          upgradeDb.createObjectStore(storeName);
+        }
+      };
+      upgradeRequest.onerror = () => reject(upgradeRequest.error);
+      upgradeRequest.onsuccess = () => resolve(upgradeRequest.result);
+    };
+  });
+
+/** 写入（覆盖）一条记录。value 通过结构化克隆存储，支持 Map / Set 等结构。 */
+export const idbSet = async (dbName: string, storeName: string, key: IDBValidKey, value: unknown): Promise<void> => {
+  const db = await openIndexedDB(dbName, storeName);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      tx.objectStore(storeName).put(value, key);
+      tx.oncomplete = () => resolve();
+      tx.onabort = () => reject(tx.error);
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+};
+
+/** 读取一条记录，不存在时返回 undefined。 */
+export const idbGet = async <T = unknown>(
+  dbName: string,
+  storeName: string,
+  key: IDBValidKey,
+): Promise<T | undefined> => {
+  const db = await openIndexedDB(dbName, storeName);
+  try {
+    return await new Promise<T | undefined>((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readonly');
+      const request = tx.objectStore(storeName).get(key);
+      request.onsuccess = () => resolve(request.result as T | undefined);
+      request.onerror = () => reject(request.error);
+    });
+  } finally {
+    db.close();
+  }
+};
+
+/** 删除一条记录。 */
+export const idbDelete = async (dbName: string, storeName: string, key: IDBValidKey): Promise<void> => {
+  const db = await openIndexedDB(dbName, storeName);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      tx.objectStore(storeName).delete(key);
+      tx.oncomplete = () => resolve();
+      tx.onabort = () => reject(tx.error);
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+};

package/src/utils/undo-redo.ts

@@ -18,8 +18,59 @@
 
 import { cloneDeep } from 'lodash-es';
 
+// #region SerializedUndoRedo
+/**
+ * UndoRedo 栈的可序列化快照，用于持久化（如写入 IndexedDB）后再还原。
+ */
+export interface SerializedUndoRedo<T = any> {
+  /** 栈内全部元素（按时间正序，索引 0 为最早一步）。 */
+  elementList: T[];
+  /** 游标位置（已应用步骤数量）。 */
+  listCursor: number;
+  /** 栈容量上限。 */
+  listMaxSize: number;
+}
+// #endregion SerializedUndoRedo
+
 // #region UndoRedo
 export class UndoRedo<T = any> {
+  /**
+   * 由 {@link UndoRedo.serialize} 产出的快照重建一个 UndoRedo 实例。
+   * 游标会被夹紧到 [0, length] 区间，避免脏数据导致越界。
+   *
+   * @param options.isSavedStep 可选谓词：若提供，则把游标定位到「最近一条满足该谓词的记录」之后
+   *   （即恢复到最近一个已保存点）；找不到匹配记录时退回快照中的原游标。
+   */
+  public static fromSerialized<T = any>(
+    data: SerializedUndoRedo<T>,
+    options: { isSavedStep?: (element: T) => boolean } = {},
+  ): UndoRedo<T> {
+    const undoRedo = new UndoRedo<T>(data.listMaxSize);
+    const list = Array.isArray(data.elementList) ? data.elementList.map((item) => cloneDeep(item)) : [];
+    let cursor = Number.isFinite(data.listCursor) ? data.listCursor : list.length;
+
+    // 本地数据同样遵循容量上限：超出时裁掉最旧的记录（与 pushElement 的 shift 行为一致），并同步回退游标。
+    const overflow = list.length - undoRedo.listMaxSize;
+    if (overflow > 0) {
+      list.splice(0, overflow);
+      cursor -= overflow;
+    }
+
+    // 若指定了「已保存」谓词，则把游标移动到最近一条已保存记录之后；在裁剪后的 list 上查找以保证索引正确。
+    if (options.isSavedStep) {
+      for (let i = list.length - 1; i >= 0; i--) {
+        if (options.isSavedStep(list[i])) {
+          cursor = i + 1;
+          break;
+        }
+      }
+    }
+
+    undoRedo.elementList = list;
+    undoRedo.listCursor = Math.max(0, Math.min(cursor, list.length));
+    return undoRedo;
+  }
+
   private elementList: T[];
   private listCursor: number;
   private listMaxSize: number;
@@ -31,6 +82,18 @@ export class UndoRedo<T = any> {
     this.listMaxSize = listMaxSize > minListMaxSize ? listMaxSize : minListMaxSize;
   }
 
+  /**
+   * 导出当前栈的可序列化快照（深克隆，避免外部改动污染内部状态）。
+   * 配合 {@link UndoRedo.fromSerialized} 可在持久化后完整还原撤销/重做栈。
+   */
+  public serialize(): SerializedUndoRedo<T> {
+    return {
+      elementList: this.elementList.map((item) => cloneDeep(item)),
+      listCursor: this.listCursor,
+      listMaxSize: this.listMaxSize,
+    };
+  }
+
   public pushElement(element: T): void {
     // 新元素进来时，把游标之外的元素全部丢弃，并把新元素放进来
     this.elementList.splice(this.listCursor, this.elementList.length - this.listCursor, cloneDeep(element));
@@ -76,6 +139,31 @@ export class UndoRedo<T = any> {
     return cloneDeep(this.elementList[this.listCursor - 1]);
   }
 
+  /**
+   * 用 `element` 替换当前游标所在元素（cursor - 1），并丢弃其后的重做尾部（与 {@link pushElement} 的丢尾一致），
+   * 游标位置保持不变（元素数量不增）。cursor 为 0（无已应用元素）时不做任何操作并返回 false。
+   * 用于「连续同类记录合并」等就地替换最新一条的场景。
+   */
+  public replaceCurrentElement(element: T): boolean {
+    if (this.listCursor < 1) return false;
+    this.elementList.splice(this.listCursor - 1, this.elementList.length - (this.listCursor - 1), cloneDeep(element));
+    return true;
+  }
+
+  /**
+   * 对当前游标所在元素（cursor - 1）做就地更新；cursor 为 0（全部已撤销）时不做任何操作。
+   * 用于给「当前步骤」打标记（如标记为已保存）等元数据写入场景。
+   */
+  public updateCurrentElement(updater: (element: T) => void): void {
+    if (this.listCursor < 1) return;
+    updater(this.elementList[this.listCursor - 1]);
+  }
+
+  /** 对栈内全部元素做就地更新。用于批量清理元数据（如清空所有元素的已保存标记）。 */
+  public updateElements(updater: (element: T, index: number) => void): void {
+    this.elementList.forEach(updater);
+  }
+
   /**
    * 返回栈内全部元素的浅克隆数组（按时间顺序，索引 0 为最早一步）。
    * 仅用于历史面板等只读展示场景，不应直接修改返回值。