411 lines
9.6 KiB
Markdown
411 lines
9.6 KiB
Markdown
|
# RPA 函数规范化定义建议
|
|||
|
以下是经过规范化和统一化后的 RPA 函数定义。主要规范化的方面包括:
|
|||
|
|
|||
|
1. **方法名**:统一为驼峰命名法,前缀统一为模块名(`Lan`)+ 功能描述 + 动作。
|
|||
|
2. **参数名**:统一使用小写字母+下划线命名法。
|
|||
|
3. **可选参数**:明确标注可选参数,并使用一致的命名和格式。
|
|||
|
4. **参数命名与描述**:确保参数名简洁、描述一致且直观。
|
|||
|
5. **返回值统一**:移除冗余的变量接收参数,通过响应中返回。
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
### 规范化后的定义
|
|||
|
|
|||
|
#### 1. 文件复制操作
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.Core.CopyFile
|
|||
|
**描述**:复制文件并粘贴到指定目标路径。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- source_file_path (String, 必填):原始文件的完整路径。
|
|||
|
- target_file_path (String, 必填):目标文件夹路径。
|
|||
|
- target_file_name (String, 可选):目标文件名,默认使用原始文件名。
|
|||
|
- overwrite (Boolean, 必填):是否覆盖目标路径中的同名文件。可选值:true/false。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 2. 读取 Excel 单元格
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.Excel.ReadCell
|
|||
|
**描述**:读取 Excel 表格中指定单元格的内容。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- file_path (String, 必填):Excel 文件的完整路径。
|
|||
|
- sheet_name (String, 必填):工作表名称。
|
|||
|
- cell_name (String, 必填):单元格名称(如 A1、B2)。
|
|||
|
- password (String, 可选):Excel 文件密码。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 3. 写入 Excel 单元格
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.Excel.WriteCell
|
|||
|
**描述**:向 Excel 表格中指定单元格写入内容。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- file_path (String, 必填):Excel 文件的完整路径。
|
|||
|
- sheet_name (String, 必填):工作表名称。
|
|||
|
- cell_name (String, 必填):单元格名称(如 A1、B2)。
|
|||
|
- cell_value (Object, 必填):要写入的内容。
|
|||
|
- password (String, 可选):Excel 文件密码。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 4. 合并/取消合并单元格
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.Excel.MergeCells
|
|||
|
**描述**:合并或取消合并 Excel 表格中的单元格。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- file_path (String, 必填):Excel 文件的完整路径。
|
|||
|
- sheet_name (String, 必填):工作表名称。
|
|||
|
- range_name (String, 必填):单元格区域名称(如 A1:C3)。
|
|||
|
- option (String, 必填):操作类型,可选值:"merge"(合并)或 "unmerge"(取消合并)。
|
|||
|
- password (String, 可选):Excel 文件密码。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 5. 关闭 Word 文档
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.Word.CloseDocument
|
|||
|
**描述**:关闭指定路径下的 Word 文档。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- file_path (String, 必填):Word 文档的完整路径。
|
|||
|
- visible (Boolean, 必填):文档是否可见。可选值:true/false。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 6. 读取 Word 文档内容
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.Word.ReadDocument
|
|||
|
**描述**:读取 Word 文档中的所有文本内容。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- file_path (String, 必填):Word 文档的完整路径。
|
|||
|
- visible (Boolean, 必填):文档是否可见。可选值:true/false。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 7. 生成二维码
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.QRCode.Generate
|
|||
|
**描述**:将输入文本生成二维码图像并保存到指定路径。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- save_file_path (String, 必填):二维码图像的保存路径(需指定格式,如 example.jpg)。
|
|||
|
- text (String, 必填):要存储在二维码中的文本或 URL。
|
|||
|
- width (Int, 必填):二维码图像的宽度。
|
|||
|
- height (Int, 必填):二维码图像的高度。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 8. 解析二维码
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.QRCode.Parse
|
|||
|
**描述**:解析二维码图像并提取其中的文本数据。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- file_path (String, 必填):二维码图像的完整路径。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 9. ASCII 转字符串
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.Core.ASCIIToString
|
|||
|
**描述**:将 ASCII 编码转换为字符串。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- ascii_code (String, 必填):需要转换的 ASCII 编码字符串。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 10. 字符串转 ASCII
|
|||
|
|
|||
|
```plaintext
|
|||
|
**方法名**:Lan.Core.StringToASCII
|
|||
|
**描述**:将字符串转换为 ASCII 编码格式。
|
|||
|
|
|||
|
**参数**:
|
|||
|
- input_string (String, 必填):需要转换的字符串。
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
### 规范总结
|
|||
|
|
|||
|
1. **方法名**:采用模块前缀(如 `Lan.Core`、`Lan.Excel`)+ 功能描述 + 动作,保持一致。
|
|||
|
2. **参数命名**:统一为小写字母+下划线的命名方式,确保易读和规范。
|
|||
|
3. **参数顺序**:必填参数在前,可选参数在后。
|
|||
|
4. **参数类型**:明确标注类型(如 String、Boolean、Int)。
|
|||
|
5. **选项值标准化**:将布尔值统一为 `true/false`,其他选项如操作类型明确约束(如 "merge"、"unmerge")。
|
|||
|
6. **描述**:方法描述简洁清晰,参数的功能和用法明确统一。
|
|||
|
|
|||
|
## 返回值
|
|||
|
以下是为 RPA 函数定义提供的**统一规范返回值**。返回值结构简洁、统一,确保每个方法在执行后能够清晰地传达执行状态、结果和相关信息。
|
|||
|
|
|||
|
### 返回值统一格式
|
|||
|
|
|||
|
所有函数返回值将遵循以下 JSON 格式:
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success", // 执行状态: success / error
|
|||
|
"message": "操作成功", // 简要描述执行结果
|
|||
|
"data": { // 执行结果的具体数据
|
|||
|
"key": "value"
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z" // 服务器响应的时间戳
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
#### 字段解释:
|
|||
|
1. **status**:
|
|||
|
- `success`:操作成功。
|
|||
|
- `error`:操作失败。
|
|||
|
|
|||
|
2. **message**:简要描述执行结果的文本信息。
|
|||
|
|
|||
|
3. **data**:返回的具体数据,结构根据方法的实际执行结果而定。
|
|||
|
|
|||
|
4. **timestamp**:操作完成的时间,ISO8601 格式。
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
### 各方法返回值定义
|
|||
|
|
|||
|
#### 1. 文件复制操作 - `Lan.Core.CopyFile`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "文件复制成功",
|
|||
|
"data": {
|
|||
|
"source_file_path": "/path/to/source/fileA.txt",
|
|||
|
"target_file_path": "/path/to/destination/fileA_copy.txt",
|
|||
|
"overwrite": true
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
### 2. 读取 Excel 单元格 - `Lan.Excel.ReadCell`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "单元格读取成功",
|
|||
|
"data": {
|
|||
|
"file_path": "/path/to/excel.xlsx",
|
|||
|
"sheet_name": "Sheet1",
|
|||
|
"cell_name": "A1",
|
|||
|
"cell_value": "123"
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 3. 写入 Excel 单元格 - `Lan.Excel.WriteCell`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "单元格写入成功",
|
|||
|
"data": {
|
|||
|
"file_path": "/path/to/excel.xlsx",
|
|||
|
"sheet_name": "Sheet1",
|
|||
|
"cell_name": "A1",
|
|||
|
"cell_value": "Hello World"
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
### 4. 合并/取消合并单元格 - `Lan.Excel.MergeCells`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "单元格合并成功",
|
|||
|
"data": {
|
|||
|
"file_path": "/path/to/excel.xlsx",
|
|||
|
"sheet_name": "Sheet1",
|
|||
|
"range_name": "A1:C3",
|
|||
|
"operation": "merge"
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 5. 关闭 Word 文档 - `Lan.Word.CloseDocument`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "Word 文档关闭成功",
|
|||
|
"data": {
|
|||
|
"file_path": "/path/to/document.docx",
|
|||
|
"visible": false
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
### 6. 读取 Word 文档内容 - `Lan.Word.ReadDocument`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "文档读取成功",
|
|||
|
"data": {
|
|||
|
"file_path": "/path/to/document.docx",
|
|||
|
"content": "这是文档的全部内容。"
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 7. 生成二维码 - `Lan.QRCode.Generate`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "二维码生成成功",
|
|||
|
"data": {
|
|||
|
"save_file_path": "/path/to/qrcode.jpg",
|
|||
|
"text": "https://example.com",
|
|||
|
"width": 200,
|
|||
|
"height": 200
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 8. 解析二维码 - `Lan.QRCode.Parse`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "二维码解析成功",
|
|||
|
"data": {
|
|||
|
"file_path": "/path/to/qrcode.jpg",
|
|||
|
"text": "https://example.com"
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 9. ASCII 转字符串 - `Lan.Core.ASCIIToString`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "ASCII 转换成功",
|
|||
|
"data": {
|
|||
|
"ascii_code": "65 66 67",
|
|||
|
"result": "ABC"
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 10. 字符串转 ASCII - `Lan.Core.StringToASCII`
|
|||
|
|
|||
|
##### 返回值示例(成功):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "success",
|
|||
|
"message": "字符串转换为 ASCII 成功",
|
|||
|
"data": {
|
|||
|
"input_string": "ABC",
|
|||
|
"ascii_code": "65 66 67"
|
|||
|
},
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
#### 统一错误返回值示例
|
|||
|
|
|||
|
如果操作失败,返回以下格式的错误信息:
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"status": "error",
|
|||
|
"message": "文件路径不存在",
|
|||
|
"data": null,
|
|||
|
"timestamp": "2024-04-28T12:00:00Z"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
#### 字段说明:
|
|||
|
1. **status**:`error` 表示操作失败。
|
|||
|
2. **message**:包含错误原因的简要描述。
|
|||
|
3. **data**:失败时为 `null`。
|
|||
|
4. **timestamp**:错误发生的时间。
|
|||
|
|
|||
|
---
|
|||
|
|
|||
|
## 总结
|
|||
|
|
|||
|
### 统一规范总结:
|
|||
|
1. **方法返回值**:统一格式,包含 `status`、`message`、`data` 和 `timestamp` 字段。
|
|||
|
2. **成功返回**:返回详细的操作数据,易于跟踪和验证。
|
|||
|
3. **失败返回**:提供明确的错误消息,方便调试和处理。
|
|||
|
4. **一致性**:所有方法均遵循相同的返回值结构,增强了接口的可维护性和标准化。
|