# fsys.recycleBin 回收站操作库

`fsys.recycleBin` 封装 Windows Shell 的 `Shell.Application` COM 接口与 `SHEmptyRecycleBinW` API，用于读取、检索、还原和清空当前用户的回收站。

> 这是 Windows 专用库。回收站清空是破坏性操作，`emptySilent()` 不可撤销；请仅在确认目标后调用。

## 导入

```aardio
import fsys.recycleBin;
```

## 快速开始：查看清单

```aardio
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 项目的迭代器：

```aardio
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` 中的记录包含：

| 字段 | 说明 |
|---|---|
| `name` | 文件或目录名 |
| `originalDir` / `deletedFrom` | 删除前所在的原始目录 |
| `recyclePath` | 回收站内部 `$R...` 路径 |
| `deletedAt` | `time` 对象；某些特殊项目可能为空 |
| `deletedTimestamp` | Unix 时间戳，适合排序 |
| `deletedDate` | 可读的删除时间文本 |
| `size` | `math.size64` 对象 |
| `sizeBytes` | 便于比较的数值大小 |
| `sizeText` | Shell 本地化显示的大小文本 |
| `itemType` | Shell 本地化显示的项目类型 |
| `isFolder` | 是否目录 |
| `item` | 仅 `info()` 或 `list(true)`/`query(true)` 包含的原始 COM 项目 |

### `list(includeItem)`

返回纯数组清单。默认不保留原始 COM 项目；需要后续调用 `restore(record.item)` 时传入 `true`：

```aardio
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` 规范化路径。

```aardio
var record = fsys.recycleBin.find("example.txt", "C:\\test");
if(record){
    fsys.recycleBin.restore(record.item);
}
```

`findAll` 返回全部匹配项，未找到时返回空数组。

### `restoreFile(fileName, originalDir)`

查找并还原指定文件，成功返回 `true,record`，找不到或还原失败返回 `null,error`。

```aardio
var ok,record = fsys.recycleBin.restoreFile("example.txt", "C:\\test");
```

### `restoreLast()`

按 `System.Recycle.DateDeleted` 扩展属性得到的真实时间排序，避免直接比较受系统区域设置影响的日期文本。成功返回 `true,record`，回收站为空返回 `null,error`。

```aardio
var ok,record = fsys.recycleBin.restoreLast();
if(ok) print("已还原:", record.name, record.originalDir);
```

### `delete(path, allowUndo, progressTitle, hwndOwner)`

安全删除接口：

```aardio
// 默认移入回收站
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`：

```aardio
// 可能显示系统确认/进度界面
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()` 会永久删除当前用户回收站中的全部项目，库不会自动调用它。
