# 插件：文件读写

**Repository Path**: low-code-dev-lab/hzg-plugin-file-read-write

## Basic Information

- **Project Name**: 插件：文件读写
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文件读写插件

文件读写是面向活字格服务端命令的文件处理扩展，提供路径拼接、文件读写与删除、目录和文件查询、内容搜索、目录快照以及 HTTP/HTTPS 文件下载能力。

## 兼容与安装

- 插件版本：1.6.0.0
- 最低活字格版本：11.0.102.0
- 目标运行时：.NET 8（Windows）

构建后使用活字格插件包进行安装。命令统一位于“文件读写”分类，并在服务端执行；服务器进程账号必须拥有目标目录的读取或写入权限。

## 命令清单

| 命令 | 用途 |
| --- | --- |
| 拼接路径 | 合并两个路径片段。 |
| 读取文件 | 读取文本、图片或二进制文件。 |
| 写入文件 | 新建、覆盖或追加文件内容。 |
| 删除文件 | 删除指定文件。 |
| 判断文件是否存在 | 检查服务器文件是否存在。 |
| 获取文件列表 | 获取目录中的文件信息。 |
| 获取文件夹列表 | 获取目录中的子文件夹。 |
| 查找文件 | 按通配符、目录、大小和修改时间筛选文件。 |
| 搜索文件内容 | 在文本文件中搜索文本或正则表达式。 |
| 获取文件片段 | 按行读取文件的一部分。 |
| 生成目录快照 | 生成带深度和数量限制的目录树文本。 |
| 文件下载 | 从 HTTP 或 HTTPS 地址流式下载文件到服务器。 |

## 文件下载

“文件下载”使用 HTTP GET 请求。响应内容先写入保存目录中的临时文件，完整下载成功后再替换目标文件；请求失败、超时或写入失败时会尝试清理临时文件。目标文件已存在时会被覆盖。

### 属性

| 属性 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| URL | 是 | 空 | HTTP 或 HTTPS 绝对地址，支持公式。 |
| 点击设置 HTTP Header | 否 | 空列表 | 在弹窗中逐项设置名称和值，两者均支持公式；同名 Header 以后面的值为准。可设置 `Authorization`、`Content-Type` 等。 |
| 保存目录 | 是 | 空 | 服务器目录全路径，支持公式；目录不存在时自动创建。 |
| 新文件名 | 否 | 空 | 只允许文件名和扩展名，不允许包含目录。留空时依次采用响应 `Content-Disposition` 文件名、URL 文件名或 `download`。 |
| 超时时间（秒） | 否 | 100 | 高级属性，支持公式，有效范围为 1 到 86400 秒；覆盖请求和文件写入全过程。 |
| 将下载结果保存到变量 | 是 | 文件下载结果 | 保存结构化结果对象的变量名。 |

Header 示例：

| 名称 | 值 |
| --- | --- |
| Authorization | `Bearer <token>` |
| Content-Type | `application/octet-stream` |
| X-Trace-Id | `{{追踪ID}}` |

令牌等敏感值应来自活字格变量或安全配置，不要直接写入命令定义。账号只应获得下载目标所需的最小权限。

### 结果变量

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| Success | Boolean | 是否下载成功。 |
| ErrCode | Number | 错误码，成功为 0。 |
| Message | String | 下载结果或错误说明。 |
| Url | String | 请求的文件地址。 |
| FilePath | String | 下载成功后的服务器文件全路径。 |
| FileName | String | 下载成功后的文件名。 |
| BytesWritten | Number | 写入文件的字节数。 |
| StatusCode | Number | HTTP 响应状态码；未收到响应时为 0。 |

错误码：

| ErrCode | 含义 |
| --- | --- |
| 0 | 成功。 |
| 1 | URL、文件名、超时时间或 Header 等输入无效。 |
| 2 | 服务器返回非成功 HTTP 状态码。 |
| 3 | 下载超时。 |
| 4 | DNS、连接或其他网络请求失败。 |
| 5 | 保存目录权限或文件写入失败。 |
| 9 | 未分类异常。 |

### 示例

下载受保护的报表：

1. URL 设置为报表下载地址。
2. 在 HTTP Header 弹窗中添加 `Authorization`，值使用保存 Token 的变量公式。
3. 保存目录设置为服务器上的报表目录。
4. 新文件名设置为 `monthly-report.xlsx`。
5. 执行后检查 `文件下载结果.Success`，成功时从 `FilePath` 获取完整路径。

### 排查与限制

- `ErrCode = 1`：检查 URL 是否为绝对 HTTP/HTTPS 地址、新文件名是否包含路径字符，以及超时时间是否在有效范围内。
- `ErrCode = 2`：检查 `StatusCode`，常见原因是认证失败、资源不存在或服务器限流。
- `ErrCode = 3/4`：检查服务器的 DNS、代理、防火墙和目标地址可达性，并按文件大小调整超时时间。
- `ErrCode = 5`：确认活字格服务进程账号对保存目录拥有创建、写入、覆盖和删除临时文件的权限。
- 命令不限制下载文件大小；应结合服务器磁盘容量、来源可信度和超时时间控制使用范围。
- 下载地址和响应文件名来自外部系统。命令会阻止新文件名包含目录，并清理响应文件名中的无效字符，但仍应仅访问可信来源。