# apass-opensdk-hugong

> 面向飞书低代码平台（APASS）开发者的 Node.js SDK，提供常用工具函数与便捷封装。

---

## 目录

- [简介](#简介)
- [安装](#安装)
- [快速开始](#快速开始)
- [常用工具](#常用工具)
  - [时间相关](#时间相关)
  - [安全取值](#安全取值)
  - [线程睡眠](#线程睡眠)
  - [数组操作](#数组操作)
- [文件操作（APass 相关）](#文件操作apass-相关)
  - [文件上传](#文件上传)
  - [文件下载](#文件下载)
  - [CSV 解析](#csv-解析)
  - [Excel 解析](#excel-解析)
  - [Excel 导出](#excel-导出)
- [多语言工具](#多语言工具)
- [交流学习](#交流学习)

---

## 简介

**apass-opensdk-hugong** 是一个 Node.js SDK，提供了一系列常用的功能封装。

**适用人群：**
- 飞书低代码平台（APASS）开发人员
- 传统 Node.js 开发人员

---

## 安装

在飞书低代码平台（云函数）中安装：

> 依赖管理 → 右侧 → 搜索：`apass-opensdk-hugong`
> ⚠️记得版本要升级到最新版本
---

## 快速开始

```javascript
const Hugong = require('apass-opensdk-hugong');

// 初始化（主函数内），函数外不需要入参 logger
const hg = new Hugong(logger);

// 也可以单独初始化 logger 模块
hg.setLogger(logger);
```

---

## 常用工具

### 时间相关

```javascript
// 记录时间
hg.newTime();

// 打印运行时间
hg.printTime();
```

### 安全取值

```javascript
// 安全的深层取值，避免 undefined 报错
hg.toValue({ a: { b: { c: 'value' } } }, 'a.b.c', 'default value');
```

### 线程睡眠

```javascript
// 线程睡眠（毫秒）
await hg.sleep(2000);
```

### 数组操作

#### 1. 生成指定范围的数组

```javascript
const rangeValue = hg.utils.range(5, 50, 3);
// => [ 5, 8, 11, 14, 17, 20, 23, 26, 29, 32, 35, 38, 41, 44, 47, 50 ]
```

#### 2. 数组分块

```javascript
const chunkValue = hg.utils.chunkAll(rangeValue, 5);
// => [ [ 5, 8, 11, 14, 17 ], [ 20, 23, 26, 29, 32 ], [ 35, 38, 41, 44, 47 ], [ 50 ] ]
```

#### 3. 数组分块（输出方式一）

```javascript
hg.utils.splitArray([/* ... */], 5);
// => [ [5, 8, 11, 14, 17], [20, 23, 26, 29, 32], [35, 38, 41, 44, 47], [50] ]
```

#### 4. 数组分块（输出方式二，推荐大数据量使用）

每次输出指定条数，处理完成后继续下次执行：

```javascript
await hg.utils.splitArray([/* ... */], 10, async (items) => {
  // do something
});
```

#### 5. 移除重复项

```javascript
hg.utils.unique([1, 2, 3, 1, 2, 3]);
// => [1, 2, 3]
```

---

## 文件操作（APass 相关）

### 文件上传

**从网络下载文件后上传到飞书租户空间，返回上传后的文件信息：**

```javascript
// 基础用法
await hg.utils.file.downloadFileToUpload(url);

// 带鉴权 header
await hg.utils.file.downloadFileToUpload(url, { Authorization: `...` });
```

**保存数据到本地环境：**

```javascript
// 保存数据到本地环境中，方便查看接口返回的数据
hg.utils.file.saveDataToEnv(data, path);
```

### 文件下载

**从飞书租户空间下载文件到本地环境：**

```javascript
const file_info = { id, mime_type, /* ... */ };
const file_path = '/tmp/xxx'; // 可选，不填则默认当前时间戳

await hg.utils.file.downloadFileToTmp(file_info, file_path);
```

**Token 文件下载：**

```javascript
const file_info = { token, mime_type, /* ... */ };

await hg.utils.file.downloadFileByToeknToTmp(file_info, file_path);
```

### CSV 解析

> `file_path` 必须是本地环境的文件路径（如 `/tmp/aaa.csv`），可先用 `downloadFileToTmp` 下载文件到本地环境。

**示例 1：读取完成后返回数组（小文件推荐）**

```javascript
const list = await hg.utils.file.csvRead(file_path);
```

**示例 2：逐行回调（超过 5000 条建议使用，防止内存溢出）**

```javascript
await hg.utils.file.csvRead(file_path, async (row) => {
  // do something
});
```

### Excel 解析

> `file_path` 必须是本地环境的文件路径（如 `/tmp/aaa.xlsx`），可先用 `downloadFileToTmp` 下载文件到本地环境。

```javascript
const list = hg.utils.file.xlsxReaderAll(file_path);
```

> **注意：** 建议小文件使用（10M 以下），如果是大文件（10M 以上）建议转换成 CSV 使用上面的方法。亲自测试 10 万条 CSV 读取正常。

### Excel 导出

```javascript
await hg.utils.file.exportExcelFile(records, fields, fileName);
```

**`fields` 列配置说明：**

| 参数 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `key` | `string` | ✅ | 列唯一标识（对应数据字段键） |
| `header` | `string` | ✅ | 列表头显示文本 |
| `render` | `Function` | - | 自定义渲染函数 `(value, record) => value` |
| `enums` | `Array` | - | 枚举配置，格式如 `[{ name: [{ language_code, text }], api_alias }]` |
| `type` | `string` | - | 列类型：`'Date'` \| `'Float'` \| `'Region'` |

---

## 多语言工具

**对象数据新增多语言对象：**

将开放平台返回的多语言对象转换为 `application.constants.type.Multilingual` 格式：

```javascript
// 数组形式
hg.toMultilingualByOpenPlatform([
  { lang: 'en-US', value: 'Regular' },
  { lang: 'zh-CN', value: '正式' }
]);

// 多参数形式
hg.toMultilingualByOpenPlatform(zh, en);

// 将多语言对象提取文本
ss.toTextByMultilingual([])
```

---

## 交流学习

> 从事飞书低代码平台（APASS）开发 3 年，欢迎交流学习 🎉

**微信：** `IAMRuiyu`