# @gatekeeper\_technology/report-utils 中文文档

规范地址：https://npmcn.com/package/%40gatekeeper_technology/report-utils/

版本：1\.3\.3
npm 元数据更新时间：2026-07-10T12:48:15.466Z
中文译文更新时间：2026-11-15T23:54:53.538Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gatekeeper_technology/report-utils
原文对照：https://npmcn.com/package/%40gatekeeper_technology/report-utils/?lang=original
项目主页：https://github.com/gatekeeper-technology/report-utils#readme
源码仓库：https://github.com/gatekeeper-technology/report-utils

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：66.4 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2022-02-18T08:24:02.215Z
- 最新版本发布：2026-07-10T12:48:15.326Z
- 近 30 天下载量：13280（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 1 个）

## 中文简介

守门员的pdf/电子邮件Utils - 在国家预防机制共享

## 安装

```sh
npm install @gatekeeper_technology/report-utils
```

也可以使用：`pnpm add @gatekeeper_technology/report-utils`、`yarn add @gatekeeper_technology/report-utils`、`bun add @gatekeeper_technology/report-utils`

## README

# 守门员报告 Utils

共享 PDF, 电子邮件, 日期, 附件, 以及 Gatekeeper JourneyApps 报告的显示助手 .

## 安装

将软件包添加到 JourneyApps CloudCode 任务中 :

```json
{
  "dependencies": {
    "@gatekeeper_technology/report-utils": "1.3.3"
  }
}
```

创建一个 `.npmrc` 在 CloudCode 任务中使用 1Password 的只读 npm 令牌 :

```text
//registry.npmjs.org/:_authToken=<read-only-npm-token>
```

然后导入助手 :

```js
const reportUtils = require("@gatekeeper_technology/report-utils");
```

## 共同实例

### 格式化日期

```js
const {
  displayDate,
  displayDateTime,
  displayTime,
  displayTimeWithSeconds,
  getOffsetDate,
  getStartOfWeek,
  getEndOfWeek,
  getWeekNumber,
  isSameDay,
  compareDates,
} = require("@gatekeeper_technology/report-utils");

const date = new Date(2026, 6, 10, 8, 30, 0);

displayDate(date);                  // "10 Jul 2026"
displayDate(date, "long");          // "10 July 2026"
displayTime(date);                  // "08:30"
displayTimeWithSeconds(date);       // "08:30:00"
displayDateTime(date);              // "10 Jul 2026, 08:30"

getOffsetDate(date, 7);             // date plus 7 days
getStartOfWeek(date);               // Monday start, ISO mode by default
getEndOfWeek(date);                 // Sunday end, ISO mode by default
getWeekNumber(date);                // calendar week number

isSameDay(date, new Date());        // true/false
compareDates(date, new Date());     // -1, 0, or 1
```

非日期投入一般返回 `null` 用于日期比较帮助者和 `"-"` 用于显示助手.

### 准备发送Grid 收件人

```js
const {
  getToEmailsArray,
  setCheckWhitelistEnvironments,
} = require("@gatekeeper_technology/report-utils");

const recipients = getToEmailsArray(
  [" Manager@Example.com ", "auditor@example.com; area@example.com"],
  ["manager@example.com", "ops@example.com"],
  "staging",
  ["manager@example.com", "area@example.com"]
);

// recipients:
// {
//   to: [{ email: "manager@example.com" }, { email: "area@example.com" }],
//   cc: []
// }
```

`getToEmailsArray` 三进制、小写、去重复、拆分逗号/半结号分隔字符串、去除已输入的 CC 地址,以及用白名单过滤 `staging` 财务报告和审定财务报表 `testing`。 。 。 .

要改变使用白名单的环境 :

```js
setCheckWhitelistEnvironments(["testing", "staging", "production"]);
```

### 生成 HTML 并保存 PDF 附录

```js
const {
  generateHTML,
  postToJourneyBackend,
} = require("@gatekeeper_technology/report-utils");

async function createReport(request, data) {
  const html = generateHTML(data, __dirname, "templates/report.html");

  const saved = await postToJourneyBackend(
    request,
    "report_pdf",
    html,
    `report-${request.id}.pdf`,
    process.env.JOURNEY_PDF_REPORTS_TOKEN
  );

  if (!saved) {
    throw new Error("Report PDF could not be generated or saved");
  }
}
```

`generateHTML` 读取和编译 Handlebars 模板. `postToJourneyBackend` 生成 PDF 与 `@journeyapps/pdf-reports`,创建行进录 `Attachment`,将其分配给请求的字段,并保存对象.

### 在报表中使用相片和签名

```js
const {
  getImageContentForPDF,
  isAttachmentsUploaded,
  loadAttachments,
  loadPhotoOrSignature,
} = require("@gatekeeper_technology/report-utils");

async function buildReportData(inspection) {
  try {
    isAttachmentsUploaded(inspection);
  } catch (error) {
    if (error.cause === "attachments-uploading") {
      // Reschedule the CloudCode task using the app's normal retry pattern.
      throw error;
    }
    throw error;
  }

  return loadAttachments({}, inspection);
}

async function addSignature(inspection) {
  return loadPhotoOrSignature(inspection, "customer_signature");
}

async function addImage(inspection) {
  return {
    image_url: await getImageContentForPDF(inspection.photo, "url"),
    image_base64: await getImageContentForPDF(inspection.photo, "base64"),
  };
}
```

随附帮助 `cause: "attachments-uploading"` 当 JourneyApps 附件未完成上传时 。 抓住这个错误, 从调用应用程序中重新安排任务 .

何时 `type` 实值 `"base64"`, (中文(简体) ), `getImageContentForPDF` 从基数64有效载荷(PNG,JPEG,GIF,WebP,SVG)中检测出图像MIME类型,回落到附件URL扩展,再回落到PNG.

### 显示 JourneyApps 字段和排序数据

```js
const {
  formatText,
  getDisplayLabel,
  getDisplayValue,
  sortArrayByField,
} = require("@gatekeeper_technology/report-utils");

const label = getDisplayLabel(store, "store_type");
const value = getDisplayValue(store, "store_type");

formatText(" Store Visit / Audit ");      // "store_visit_audit"
formatText(" Store Visit / Audit ", "higher"); // "STORE_VISIT_AUDIT"

const stores = [
  { name: "Cape Town", score: 88 },
  { name: "Durban", score: 72 },
];

sortArrayByField(stores, "score", -1);    // sorts highest score first
```

`sortArrayByField` 使用 JavaScript 的本地语言 `Array.sort`,因此它使原始阵列变异.

## 导出帮助

### 日期和时间

-   `displayDate(date, monthLength)`
-   `displayDateTime(date, monthLength)`
-   `displayTime(date)`
-   `displayTimeWithSeconds(date)`
-   `getOffsetDate(originalDate, offsetDays)`
-   `getStartOfWeek(date, iso)`
-   `getEndOfWeek(date, iso)`
-   `getWeekNumber(date, iso)`
-   `isSameDay(date1, date2)`
-   `compareDates(date1, date2)`

### 电子邮件

-   `getToEmailsArray(toArray, ccArray, env, whitelist)`
-   `setCheckWhitelistEnvironments(environments)`
-   `storeValidEmail(emailObject, email)`
-   `validateEmail(email)`

### 附录 和 PDF 数据

-   `getImageContentForPDF(image, type)`
-   `loadImageBase64(path)`
-   `loadAttachments(target, objectToCheck)`
-   `loadPhotoOrSignature(object, fieldName)`
-   `isAttachmentsUploaded(objectToCheck)`
-   `isAttachmentUploaded(object, fieldName)`
-   `generateHTML(data, dirName, fileName)`
-   `postToJourneyBackend(object, fieldName, pdfHtml, fileName, token)`

### 常规

-   `getDisplayValue(object, field)`
-   `getDisplayLabel(object, field)`
-   `formatText(text, type)`
-   `sortArrayByField(objectArray, fieldName, sortDirection)`

## 发展

从 1Password 安装已发布 npm 令牌 :

```text
//registry.npmjs.org/:_authToken=<publish-npm-token>
```

发布清单 :

1.  在 `src/*.ts` 并导出新的助手 `index.ts`。 。 。 .
2.  行为改变时添加或更新 Jest 测试.
3.  更新版本为 `package.json`。 。 。 .
4.  下面添加一个更改日志条目 .
5.  运行 `npm test`。 。 。 .
6.  发布方式 `npm publish`。 。 。 .
7.  提交并推进发布.

## 更改日志

### \[1.3.3\]

#### 固定

-   `getImageContentForPDF` 现在检测Base64数据URI(PNG,JPEG,GIF,WebP,SVG)的正确MIME类型,而不是将非SVG附件作为PNG处理.
-   日期帮助者现在将无效的日期值视为无效并返回 `null` 编号 : `"-"` 见文件.

#### 已更改

-   重写 README 有安装步骤、 使用示例和导出助手参考 .
-   将过时的照片附件测试替换为MIME检测、上传检查和本地图像加载的覆盖.
-   与当前行为一致的通用测试和日期测试,并添加了电子邮件功能覆盖.
-   添加的游戏 + `ts-jest` 因此TypeScript源可以直接测试.

### \[1.3.2\]

#### 已更改

-   弹出 `@journeyapps/db` 从 `^8.0.10` 改为 `^8.1.1`。 。 。 .

### \[1.3.1\]

#### 已更改

-   弹出 `@gatekeeper_technology/rollbar-utils` 改为 `^1.2.4`。 。 。 .

### \[1.3.0\]

#### 已更改

-   将软件包版本跳出到 `1.3.0`。 。 。 .
-   弹出 `@gatekeeper_technology/rollbar-utils` 改为 `^1.2.3`。 。 。 .
-   弹出 `@journeyapps/db` 改为 `^8.0.10`。 。 。 .
-   删除了未使用的 `@journeyapps/cloudcode` 依赖性.

### \[1.2.3\]

#### 已更改

-   弹出 `@gatekeeper_technology/rollbar-utils` 从 `1.1.1` 改为 `^1.2.2`。 。 。 .

### \[1.2.2\]

#### 固定

-   固定 `postToJourneyBackend` 所以当目标字段缺失时它会抛出,而不是当球段存在时抛出.

#### 已更改

-   添加参数文档 `generateHTML`。 。 。 .

### \[1.2.1\]

#### 删除

-   `dist` 忽略文件在 `.npmignore`。 。 。 .

### \[1.2.0\]

#### 已添加

-   已添加 `postToJourneyBackend` 函数
-   已添加 `journeyApps` npm 包作为依赖性来帮助报告UTI 包.
-   已添加 `sortArrayByField` 函数
-   已添加 `generateHTML` 函数
-   已添加 `formatText` 函数
-   已添加 `getImageContentForPDF` 函数

#### 已更改

-   移动到类型脚本
-   所有日期功能现在都能够接受 `Day` 变量.
-   `.gitignore` 文件现在忽略了编译的文件.
-   `isAttachment(s)Uploaded` 函数不再重新安排。 它现在抛出一个错误的原因= `attachments-uploading`

### \[1.1.10\]

#### 删除

-   删除 `loadBase64` 函数在对时间的比赛中.

### \[1.1.9\]

#### 已添加

-   测试案例
-   格式Text, 排序ArrayBy Field并生成 HTML 函数
-   .d.ts 文档.

### \[1.1.8\]

#### 已更改

-   在一般提法上添加更多验证

#### 已添加

-   单位测试Utils将军.

#### 删除

-   日期 Utils 上的控制台. error () .

### \[1.1.7\]

#### 已更改

-   抛出错误的固定方式
-   增加了一个带有小内部图案的新图案文件夹

### \[1.1.6\]

#### 已更改

-   重试任务时, 我们不需要指定 CloudCode 任务名称, 因为可以通过程序访问它

### \[1.1.5\]

#### 已添加

-   isSameDay:检查给定的两个日期是否在同一天倒下(第二个日期值默认为现在).
-   比较数据:检查给定的两个日期是否在同一日期和时间(返回0)上倒下,日期1在日期2(返回-1)之前,否则返回1(第二次日期值缺省至今).

#### 删除

-   今日: 可以通过 IsSameDay () 函数使用
-   isPastDate和 isFutureDate:可以通过比较Dates()函数成为用户

#### 已更改

-   改进测试文件( WIP)

### \[1.1.4\]

#### 已添加

-   等分数
-   等效时间
-   当今
-   获取开始Week
-   获取周深
-   获得周数
-   未来日期
-   边框

### \[1.1.3\]

#### 固定

-   无法导入错误 `report-utils` 软件包 `/mobile` 一个App的一面.

### \[1.1.2\]

#### 已更改

-   家 移动 `loadImageBase64` 函数改为 `index.js` 以查看所需("fs")问题是否已经解决.

### \[1.1.1\]

#### 已更改

-   \[测试\]将要求("fs")移出功能.

### \[1.1.0\]

#### 已更改

-   重构文件结构以区分关切 .
-   已替换 `displayPhoto` 与 `journeyPhotoToBase64`,它现在有一个更描述性的名字
-   已替换 `loadPhotoOrSignature` 与 `getPhotoOrSignatureData`,现在由开发者将数据装入数据散列.
-   已替换 `loadSignatureBase64` 与 `encodeBase64ImagePNG`,重新命名函数,并将输入参数改为实际图像数据.

### \[1.00.07\] (中文(简体) )

#### 已添加

-   `index.js`: 添加了指定在何种环境中启用电子邮件白名单的能力 .

### \[1.00.06\]

#### 已更改

-   `index.js`: 在检查是否有效之前, 电子邮件先被剪切并切换到下Case .

### \[1.00.05\]

#### 已更改

-   `index.js`: 改变了方式 `loadAttachments` 函数收到重试 计数值.

### \[1.00.04\]

#### 固定

-   `index.js`: 错误,其中 `loadPhotoOrSignature` 函数已过时.

### \[1.00.03\]

#### 已更改

-   `index.js`: 电子邮件检查现在将所有邮件转换为小写后再检查复制件 .

### \[1.00.02\]

#### 已添加

-   `index.js`: 添加函数 `displayTimeWithSeconds`。 。 。 .

#### 已更改

-   `index.js`页:1.

### \[1.00.01\]

#### 已更改

-   `Readme.md`:解释有所改进.
-   `index.js`: 已添加函数 `displayDateTime` 财务报告和审定财务报表 `displayTime`。 。 。 .

### \[1.0

#### 已添加

-   `package.json`: 已补.
-   `index.js`: 添加并配有守门员手提箱功能.
-   `.npmignore`: 已补.
-   `.gitignore`: 已补.
-   `README.md`:添加了描述,设置和更改日志.

## 常见问题

### @gatekeeper\_technology/report-utils 是什么？

守门员的pdf/电子邮件Utils - 在国家预防机制共享

### 如何安装 @gatekeeper\_technology/report-utils？

在项目目录运行 npm install @gatekeeper\_technology/report-utils，或使用 pnpm add / yarn add / bun add。

### @gatekeeper\_technology/report-utils 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gatekeeper\_technology/report-utils 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gatekeeper\_technology/report-utils 可以商用吗？

@gatekeeper\_technology/report-utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gatekeeper\_technology/report-utils 的下载量有多少？

根据 npm 官方下载统计，@gatekeeper\_technology/report-utils 在 2026/10/16 – 2026/11/14 这 30 天内被下载 13,280 次，日均约 443 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gatekeeper\_technology/report-utils 还在维护吗？

最新版本 1\.3\.3 发布于 2026/07/10（4 个月前）；至今共发布 28 个版本，其中过去 12 个月发布了 1 个；首次发布于 2022/02/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

