Path: API › 文件管理

`POST /files`

获取指定路径下的目录和文件列表，支持分页、排序、搜索。返回每项的详细信息（大小、权限、修改时间等）。

## Request body

_Required._

- `action123.request_time` (string, required) — Unix 时间戳。
- `action123.request_token` (string, required) — 按 API 概览生成的签名。
- `action123.action` (string, required) — 具体操作名称。
  - one of `"GetDir"`
- `action123.path` (string, required) — 目录路径，如 `/www/wwwroot/testapi.bt.local`
- `action123.p` (integer, optional) — 页码，默认 `1`
- `action123.search` (string, optional) — 搜索关键词
- `action123.sort` (string, optional) — 排序字段：`name`/`size`/`mtime`/`permission`/`owner`

## Example request

```text
{
  "request_time": "string",
  "request_token": "string",
  "action": "GetDir",
  "path": "string",
  "p": 0,
  "search": "string",
  "sort": "string"
}
```

## Code samples

### cURL（填写面板地址与签名）

```curl
curl --request POST \
  --url "https://your-panel.example.com:8888/files" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "request_time=<Unix时间戳>" \
  --data-urlencode "request_token=<按 API 概览生成的签名>" \
  --data-urlencode "action=GetDir" \
  --data-urlencode "path=<path>"
```

## Responses

### default

接口响应，业务状态见下方详细说明。

#### Example

```json
{
  "PATH": "/www/wwwroot/testapi.bt.local",
  "DIR": [],
  "FILES": [
    "404.html;138;1779435866;644;www;;0;0;0;0;;0",
    "index.html;917;...;644;www;..."
  ],
  "PAGE": "<div>分页</div>",
  "STORE": [],
  "FILE_RECYCLE": false
}
```

- `action123.response.default.PATH` (string, optional) — 当前路径
- `action123.response.default.DIR` (array<unknown>, optional) — 子目录列表，每项格式：`name;size;mtime;permission;owner;...`
- `action123.response.default.FILES` (array<unknown>, optional) — 文件列表，格式同上
- `action123.response.default.PAGE` (string, optional) — 分页 HTML
- `action123.response.default.STORE` (array<unknown>, optional) — 收藏的路径列表
- `action123.response.default.FILE_RECYCLE` (boolean, optional) — 是否开启回收站


## GetDir

获取指定路径下的目录和文件列表，支持分页、排序、搜索。返回每项的详细信息（大小、权限、修改时间等）。

- **路由**：`POST /files`
- **action**：`GetDir`

## 输入参数

| 参数名称 | 必选 | 类型 | 描述 |
|----------|------|------|------|
| action | 是 | String | 固定值 `GetDir` |
| path | 是 | String | 目录路径，如 `/www/wwwroot/testapi.bt.local` |
| p | 否 | Integer | 页码，默认 `1` |
| search | 否 | String | 搜索关键词 |
| sort | 否 | String | 排序字段：`name`/`size`/`mtime`/`permission`/`owner` |

## 输出参数

| 参数名称 | 类型 | 描述 |
|----------|------|------|
| PATH | String | 当前路径 |
| DIR | Array | 子目录列表，每项格式：`name;size;mtime;permission;owner;...` |
| FILES | Array | 文件列表，格式同上 |
| PAGE | String | 分页 HTML |
| STORE | Array | 收藏的路径列表 |
| FILE_RECYCLE | Boolean | 是否开启回收站 |

## 示例

### 请求

```
POST /files HTTP/1.1
Content-Type: application/x-www-form-urlencoded

request_time=1700000000&request_token=xxx&action=GetDir&path=/www/wwwroot/testapi.bt.local&p=1
```

### 响应

```json
{
    "PATH": "/www/wwwroot/testapi.bt.local",
    "DIR": [],
    "FILES": ["404.html;138;1779435866;644;www;;0;0;0;0;;0", "index.html;917;...;644;www;..."],
    "PAGE": "<div>分页</div>",
    "STORE": [],
    "FILE_RECYCLE": false
}
```