# @aglyn/shared-util-tools 中文文档

规范地址：https://npmcn.com/package/%40aglyn/shared-util-tools/

版本：1\.18\.0
npm 元数据更新时间：2026-11-07T06:44:25.895Z
中文译文更新时间：2026-11-05T20:31:40.388Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aglyn/shared-util-tools
原文对照：https://npmcn.com/package/%40aglyn/shared-util-tools/?lang=original
项目主页：https://aglyn.com/
源码仓库：https://github.com/aglyn/aglyn

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

- 包体积（解压后）：957 kB，324 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-09-20T23:54:52.825Z
- 最新版本发布：2026-11-07T06:44:25.534Z
- 近 30 天下载量：26422（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：152（近 12 个月 152 个）

## 中文简介

一般用途 TypeScript 帮助器:类型守护器,阵列和对象工具,深取/设置,克隆,JSON和Base64的串行化,外加几个更大的独立模块(线性时间正格克克引擎,AES-GCM密盒,WCAG对比数学,HTML逃出,

## 安装

```sh
npm install @aglyn/shared-util-tools
```

也可以使用：`pnpm add @aglyn/shared-util-tools`、`yarn add @aglyn/shared-util-tools`、`bun add @aglyn/shared-util-tools`

## README

# @aglyn/ 共享工具

一般用途的TypeScript帮助器:类型守护器,阵列和对象工具,深取/设置,克隆,JSON和Base64序列化,外加几个更大的独立模块(一个线性时间的regex引擎,一个AES-GCM密箱,WCAG对比数学,HTML逃出,一个PDF写入器). 它是大多数Aglyn包的附属物,可以自行使用.

> 从Aglyn monorepo出版到npm. 随后的版本 [语义版本](https://semver.org/)。 。 。 .

## 安装

```
npm install @aglyn/shared-util-tools
```

无对等依存.

## 首先读取: 根导入补丁 `Array.prototype`

`package.json` 列表 `./src/lib/array/array-overrides.*` 下级 `sideEffects`,然后包根再导出该模块。 这么说吧 `import ... from '@aglyn/shared-util-tools'` 运行它, 捆绑者被告知不要放弃它.

确切地说,它的作用是: `Object.defineProperty` 它定义了八种方法 `Array.prototype`每个不可想象、可书写和可配置的,它在全球宣布 `Array<T>` TypeScript 接口. 它无条件定义它们,所以已经存在的同名地产会被覆盖.

| 方法 | 行为 |
| --- | --- |
| `$_cloneShallow()` | 浅复制件( lodash) `clone`(中文(简体) ) |
| `$_cloneDeep()` | 深层复制件( lodash) `cloneDeep`(中文(简体) ) |
| `$_moveAtIndex(index, newIndex)` | 移动项目,使数组变异 `newIndex` 实值 `NaN` |
| `$_pushAtIndex(index, ...items)` | 插入时间 `index`,变异 `index` 实值 `NaN` |
| `$_removeItem(item)` | 删除第一个完全相等的项目, 变异 |
| `$_removeAtIndex(index)` | 删除一个项目, 变异 |
| `$_replaceAtIndex(index, item)` | 替换一个项目,变异 |
| `$_truthy()` | 返回不含 falsy 项的新数组 |

变异方法返回相同的数组. 因为地产是不可想象的 它们不会出现在 `for...in`, (中文(简体) ), `Object.keys` 或者说 `JSON.stringify`。不替换内置方法。 (全球类型的宣言提供了 `$_pushAtIndex` 签名 `(index, newIndex)`;执行是 `(index, ...items)`. ) (中文(简体) )

为了避免补丁,通过子路径而不是从根导入. 此包中没有其它模块导入 `array-overrides`,例如,每个帮助补丁包都作为普通功能提供 `@aglyn/shared-util-tools/array/array-move-at-index`。注意: `@aglyn/shared-util-dom` 财务报告和审定财务报表 `@aglyn/shared-util-errors` 导入根,所以它们也应用了补丁.

## 里面有什么东西

从软件包根 :

-   全体警卫 `_`\- 前缀: `_isArr`, (中文(简体) ), `_isObj`, (中文(简体) ), `_isNum`, (中文(简体) ), `_isBool`, (中文(简体) ), `_isNull`, (中文(简体) ), `_isUndOrNull`, (中文(简体) ), `_isStrEmpty`, (中文(简体) ), `_isPromiseLike`, (中文(简体) ), `_hasOwnProperty` 和其余部分 `src/lib/guards/lib`。 。 。 .
-   矩阵 : `arraySafe`, (中文(简体) ), `arrayFrom`, (中文(简体) ), `arrayFromLength`, (中文(简体) ), `arrayCopyShallow`, (中文(简体) ), `arrayCopyDeep`, (中文(简体) ), `arrayMoveAtIndex`, (中文(简体) ), `arrayPushAtIndex`, (中文(简体) ), `arrayRemoveItem`, (中文(简体) ), `arrayRemoveAtIndex`, (中文(简体) ), `arrayUpdate`, (中文(简体) ), `arrayUpdateAtIndex`, (中文(简体) ), `arraySortBy`, (中文(简体) ), `arraySortByDeepProperty`, (中文(简体) ), `arrayOfEntriesToObject`。 。 。 .
-   对象 : `objectGetDeepProperty`, (中文(简体) ), `objectSetDeepProperty`, (中文(简体) ), `objectClone`, (中文(简体) ), `objectCloneDeep`, (中文(简体) ), `objectDeleteProperty`, (中文(简体) ), `objectRemap`, (中文(简体) ), `objectSafe`, (中文(简体) ), `objectUpdate`, (中文(简体) ), `objectGetKeysAndSymbolProperties`, (中文(简体) ), `getProperty`, (中文(简体) ), `getStaticField`。 。 。 .
-   数值 : `truthy`, (中文(简体) ), `truth`, (中文(简体) ), `falsy`, (中文(简体) ), `noop`, (中文(简体) ), `str`, (中文(简体) ), `trim`, (中文(简体) ), `length`, (中文(简体) ), `toNum`, (中文(简体) ), `numberToHexadecimal`, (中文(简体) ), `numberFromHexadecimal`, (中文(简体) ), `numeronym`, (中文(简体) ), `splitDisplayName`,则 `compare` 运算符及其运算符类型.
-   位标记 : `bitwiseHasAttribute`, (中文(简体) ), `bitwiseHasAllAttributes`, (中文(简体) ), `bitwiseHasOnlyAttributes`。 。 。 .
-   序列化 : `jsonSerialize`, (中文(简体) ), `jsonDeserialize`, (中文(简体) ), `base64IsomorphicEncode`, (中文(简体) ), `base64IsomorphicDecode`。 。 。 .
-   类别和职能: `applyMixins`, (中文(简体) ), `createChainedFunction`, (中文(简体) ), `getDisplayName`, (中文(简体) ), `interopDefault`, (中文(简体) ), `noSideEffects`, (中文(简体) ), `cloneDeep`, (中文(简体) ), `copyShallow`, (中文(简体) ), `Crud`, (中文(简体) ), `Normalized`, (中文(简体) ), `CSS`。 。 。 .

惟有顺从,故他们不被拉入每个消费者的包里

-   `@aglyn/shared-util-tools/linear-regex` - 说吧 `compileLinearPattern`, (中文(简体) ), `compileLinearTest` 联合国 `explain*` 对口单位。 一个描述图案本身并运行NFA模拟的regex引擎,因此匹配时间被输入长度时间程序长度所限定. 意指你不信任的人写的图案. 不支持回溯引用和外观 .
-   `@aglyn/shared-util-tools/secret-box` - 说吧 `createSecretBoxKey`, (中文(简体) ), `parseSecretBoxKeyring`, (中文(简体) ), `sealSecret`, (中文(简体) ), `openSecret`, (中文(简体) ), `needsReseal`, (中文(简体) ), `sealedSecretKeyId`, (中文(简体) ), `SecretBoxError`AES-256-GCM用密钥标识、密钥旋转和可选的认证上下文封存短密. 进口 `node:crypto`; 只使用服务器.
-   `@aglyn/shared-util-tools/escape-html` - 说吧 `escapeHtml(value)`,从中逃出 `& < > " '`。 。 。 .
-   `@aglyn/shared-util-tools/contrast` - 说吧 `relativeLuminanceOfRgb`, (中文(简体) ), `rgbChannelsOfHex`, (中文(简体) ), `prefersDarkInk` 和相关 SRGB 帮助者.
-   `@aglyn/shared-util-tools/serialize/php-serial-*` - 包起来 `php-serialize`。 。 。 .
-   `@aglyn/shared-util-tools/pdf/pdf-writer` - 说吧 `PdfWriter`,其下没有PDF库的 PDF 页面布局:标准 Helvetica 面部文字(左、右或中,以任何RGB颜色),将文字包裹并运行到新页面上,填充并取出矩形和规则,JPEG 图像安装在一个框上,可点击链接,每个页上其单元格包和页头行重复的表格,以及有页码的页脚. `pdfRgbFromHex` 转弯 `#rrggbb` 进入它的颜色.
-   `@aglyn/shared-util-tools/pdf/pdf-text` - 文本的一半: `toWinAnsiText` (任何字符串作为标准字体可以绘制的字符:外观类似相换入,口音掉出,emoji被去掉, `?` 用于其他脚本, `pdfString`, (中文(简体) ), `measureText` 财务报告和审定财务报表 `wrapLines` 由Adobe的 Helvetica 宽度, 和更快 `textWidth`编号 :`wrapText` 估计数.
-   `@aglyn/shared-util-tools/pdf/pdf-file` - 文件的一半: `buildPdfFile` (绘图运算符的几页,作为DCTDecode流的JPEG图像和URI链接到一个带有正确交叉引用表的PDF,相同输入的同字节), `readJpeg` (一个JPEG的大小和来自其标题的频道)和 `pdfNumber`编号 :`pdfUri`。 。 。 .

## 使用量

```ts
// Subpath imports: no prototype patch.
import { objectGetDeepProperty } from '@aglyn/shared-util-tools/object/object-get-deep-property'
import { arraySafe } from '@aglyn/shared-util-tools/array/array-safe'
import { escapeHtml } from '@aglyn/shared-util-tools/escape-html'

const city = objectGetDeepProperty<string>(user, 'address.city')
const tags = arraySafe(input.tags) // always an array
const html = `<p>${escapeHtml(comment)}</p>`
```

```ts
// Root import: same helpers, and Array.prototype gains the $_ methods.
import { _isArr, truthy } from '@aglyn/shared-util-tools'
```

## 怎样才合适

A 类 `shared` 软件包:通用,对Aglyn的模型一无所知。 共享软件包只能导入其他共享软件包; 此软件包取决于 `@aglyn/shared-data-types`, (中文(简体) ), `lodash-es` 财务报告和审定财务报表 `php-serialize`。多数单体依赖它,包括 `@aglyn/aglyn`, (中文(简体) ), `@aglyn/besigner`,共享的 UI 软件包和几个插件.

## 许可证

阿帕奇2.0 (英语). 资料来源: [https://github.com/aglyn/aglyn/tree/main/libs/shared/util/tools 页面存档备份,存于互联网档案馆](https://github.com/aglyn/aglyn/tree/main/libs/shared/util/tools)

## 常见问题

### @aglyn/shared-util-tools 是什么？

一般用途 TypeScript 帮助器:类型守护器,阵列和对象工具,深取/设置,克隆,JSON和Base64的串行化,外加几个更大的独立模块\(线性时间正格克克引擎,AES-GCM密盒,WCAG对比数学,HTML逃出,

### 如何安装 @aglyn/shared-util-tools？

在项目目录运行 npm install @aglyn/shared-util-tools，或使用 pnpm add / yarn add / bun add。

### @aglyn/shared-util-tools 支持 TypeScript 吗？

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

### @aglyn/shared-util-tools 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aglyn/shared-util-tools 可以商用吗？

@aglyn/shared-util-tools 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aglyn/shared-util-tools 的下载量有多少？

根据 npm 官方下载统计，@aglyn/shared-util-tools 在 2026/10/05 – 2026/11/03 这 30 天内被下载 26,422 次，日均约 881 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aglyn/shared-util-tools 还在维护吗？

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