docs(canvas): explain recovery and import UI lifecycle

This commit is contained in:
2026-11-12 16:27:01 +08:00
parent 97fefaa519
commit d2068d416a
4 changed files with 13 additions and 0 deletions
@@ -37,6 +37,7 @@ export function LegacyCanvasMigration(props:Props){
/** 读取并校验本作用域持久迁移记录;格式/解释版本错误也要走保留记录和暂停路径。 */
const read=()=>readCanvasMigration(localStorage,scope);
/** 迁移尝试进行中不抢租约;已有pending或finished就保持hold,正常情形取得共享锁后开放旧编辑。 */
// inspect 没有独立的在途 Promise 合并;storage/刷新可重复调用,跨页互斥由 Web Locks 与持久记录保证。
async function inspect(){
if(attempt.current||!current())return;
setChecking(true);
@@ -67,6 +68,7 @@ export function LegacyCanvasMigration(props:Props){
refresh.current=inspect;void inspect();
/** 其它页改变同一记录时重新检查;本页迁移中忽略事件,由当前尝试负责收尾。
* 待确认记录消失只说明外部变化,本页不能丢掉内存内容,先冻结并提示导出/重新打开。 */
// storage 事件来自其它文档,本页 setItem 不靠此事件更新 UI;也未按 storageArea 区分其它 Storage 来源。
const storage=(event:StorageEvent)=>{
if(event.key!==key&&event.key!==null||!current()||attempt.current)return;
// Never discard another view's in-memory content because a record vanished.
@@ -78,6 +80,7 @@ export function LegacyCanvasMigration(props:Props){
};
window.addEventListener('storage',storage);
// 卸载取消检查、拆storage监听并释放本页共享锁,不删除尚待确认的迁移记录。
// release 在此是尽力异步清理,不等待也不安装 catch;它的拒绝不进入面板 error 状态。
return()=>{controller.abort();window.removeEventListener('storage',storage);const held=lease.current;lease.current=undefined;void held?.release();};
// The port ref follows renders without re-acquiring a shared editing lease.
// eslint-disable-next-line react-hooks/exhaustive-deps
@@ -85,6 +88,7 @@ export function LegacyCanvasMigration(props:Props){
/** 新尝试先check并hold,在共享锁仍持有时prepare;释放共享锁后由迁移器申请独占锁。
* pending复用原记录resume,其它情况按rootId重新准备,不能把每次点击都变成新的迁移请求。 */
async function upgrade(){
// attempt 是同步 ref,先于首次 await 设置,区别于仅用于渲染的 running 状态。
const controller=life.current;if(!controller||controller.signal.aborted||attempt.current)return;
attempt.current=true;setRunning(true);setError('');
const current=()=>!controller.signal.aborted&&port.current.context.isCurrentIdentity();