删除与恢复

remove() 与 restore() 是两个独立的操作。库负责播放动画。元素去哪里、这对你的应用意味着什么，由你决定。

删除元素

库在分离节点前测量真实元素。节点离开布局后，视觉效果在隔离覆盖层中继续运行。

const operation = effects.remove(element, {
  retain: false,
  layout: true,
});

const result = await operation.finished;

retain 默认为 false，因此库不会保留 DOM 引用。layout 可让受影响的相邻元素平滑移动到新位置。

恢复已插入元素

应用必须先把节点插入目标位置，再调用 restore()。

container.append(element);

const operation = effects.restore(element);

await operation.finished;

元素必须已连接并具有非零尺寸。库会同步隐藏它，测量新的最终位置，完成捕获与恢复动画后显示原节点。

隐藏通过暂停的 Web Animation 实现，而非内联样式，因此在效果播放期间修改 class 或 style 都不会破坏它。由 CSS 层叠可推出一个限制：作者样式中的 !important 优先于动画，因此恢复目标上的 .card { opacity: 1 !important } 会让真实元素显示在粒子层下方。去掉目标上的 !important 即可避免，恢复一个不带该声明的包装元素同样可行。

为新元素的出现添加动画

可以使用 restore() 为新元素的出现添加动画。先将元素添加到 DOM，再调用 restore()；无需提前调用 remove()。

const message = document.createElement('aside');
message.textContent = '刚刚创建';
notifications.append(message);

effects.restore(message, { preset: 'vapor' });

操作对象

两个方法都会同步返回操作对象：

const operation = effects.remove(element);

operation.operation; // 'remove'
operation.removalId; // RemovalId | null
operation.cancel();

const result = await operation.finished;
result.status; // 'completed' | 'cancelled' | 'skipped' | 'rejected'

操作结束后，对象不会保留 DOM 元素。

取消只影响视觉

cancel() 停止动画与声音，但不会撤销内容决定：已删除元素仍保持删除，正在恢复的元素会变为可见。

因此，取消按钮或动画中途卸载视图，都不会悄悄撤销应用已经完成的内容变更。

如果元素已被第一个操作占用，第二次调用不会修改 DOM，也不会分配保留 ID。它的 finished Promise 会等待当前所有者结束，然后才以 rejected 状态完成，因此等待该操作对象不会提前结束元素的活动生命周期。

错误不会阻塞内容

捕获、音频或自定义效果失败时，删除仍会分离节点，恢复仍会显示元素。错误通过 onError 传递给应用；若没有可运行的视觉阶段，结果状态为 skipped。

const effects = new Disintegrator({
  preset: 'dust',
  onError(error, context) {
    console.error(context.operation, error);
  },
});