fsys.recycleBin 回收站操作库

fsys.recycleBin 封装 Windows Shell 的 Shell.Application COM 接口与 SHEmptyRecycleBinW API，用于读取、检索、还原和清空当前用户的回收站。

这是 Windows 专用库。回收站清空是破坏性操作，emptySilent() 不可撤销；请仅在确认目标后调用。

导入

import fsys.recycleBin;

快速开始：查看清单

import fsys.recycleBin;

var data = fsys.recycleBin.query();
print("项目数:", data.count);
print("总大小:", data.totalSizeFormatted);

for(i,record in data.items){
    print(record.name, record.originalDir, record.deletedDate, record.sizeText);
}

API

getFolder()

返回回收站 Shell 文件夹 COM 对象。它对应 NameSpace(0xA/*_CSIDL_BITBUCKET*/)。

each()

返回原始 COM 项目的迭代器：

import fsys.recycleBin;

for(i,item in fsys.recycleBin.each()){
    var record = fsys.recycleBin.info(item);
    print(record.name, record.recyclePath);
}

info(item) 与清单字段

info(item)、list() 和 query().items 中的记录包含：

list(includeItem)

返回纯数组清单。默认不保留原始 COM 项目；需要后续调用 restore(record.item) 时传入 true：

var records = fsys.recycleBin.list(true);
for(i,record in records){
    if(record.name === "example.txt"){
        fsys.recycleBin.restore(record.item);
        break;
    }
}

find(fileName, originalDir) 与 findAll(...)

文件名比较忽略大小写；originalDir 可选，比较时使用 fsys.path.cmp 规范化路径。

var record = fsys.recycleBin.find("example.txt", "C:\\test");
if(record){
    fsys.recycleBin.restore(record.item);
}

findAll 返回全部匹配项，未找到时返回空数组。

restoreFile(fileName, originalDir)

查找并还原指定文件，成功返回 true,record，找不到或还原失败返回 null,error。

var ok,record = fsys.recycleBin.restoreFile("example.txt", "C:\\test");

restoreLast()

按 System.Recycle.DateDeleted 扩展属性得到的真实时间排序，避免直接比较受系统区域设置影响的日期文本。成功返回 true,record，回收站为空返回 null,error。

var ok,record = fsys.recycleBin.restoreLast();
if(ok) print("已还原:", record.name, record.originalDir);

delete(path, allowUndo, progressTitle, hwndOwner)

安全删除接口：

// 默认移入回收站
fsys.recycleBin.delete("/example.txt");

// 等价于显式允许撤销
fsys.recycleBin.delete("/example.txt", true);

// 只有明确传入 false 才永久删除
fsys.recycleBin.delete("/example.txt", false);

empty(hwnd, flags) 与 emptySilent(hwnd)

empty 调用 SHEmptyRecycleBinW。flags 省略时为 0，保留 Windows 确认、进度和声音行为。静默标志为 0x7：

// 可能显示系统确认/进度界面
fsys.recycleBin.empty();

// 不确认、不显示进度、不播放声音；不可撤销
fsys.recycleBin.emptySilent();

如果需要将窗口作为所有者传入，可使用 empty(winform.hwnd,flags)。

常见注意事项

1. GetDetailsOf(item, 2) 是本地化显示文本，不应直接用于跨日期排序；本库使用 System.Recycle.DateDeleted。
2. 同名文件可以同时存在于回收站，建议同时指定 originalDir。
3. list() 默认不保留 COM 对象；要还原清单中的项目，请使用 list(true) 或调用 find() 后使用 record.item。
4. size 是 math.size64 对象；大文件不要只依赖 sizeBytes 的浮点数值，精确统计使用 totalSize。
5. emptySilent() 会永久删除当前用户回收站中的全部项目，库不会自动调用它。

Markdown 格式