# @adnsistemas/upng 中文文档

规范地址：https://npmcn.com/package/%40adnsistemas/upng/

版本：1\.0\.4
npm 元数据更新时间：2026-02-21T22:44:54.651Z
中文译文更新时间：2026-11-05T21:59:16.050Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：660 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-12-02T23:36:41.001Z
- 最新版本发布：2026-02-21T22:44:54.541Z
- 近 30 天下载量：14463（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

小型、快而先进的PNG/APNG编码和解码器

## 安装

```sh
npm install @adnsistemas/upng
```

也可以使用：`pnpm add @adnsistemas/upng`、`yarn add @adnsistemas/upng`、`bun add @adnsistemas/upng`

## README

# 调高  
[![NPM Version](https://img.shields.io/npm/v/@adnsistemas/upng.svg?style=flat-square)](https://www.npmjs.com/package/@adnsistemas/upng)

> 一个小型、快而先进的PNG/APNG编码和解码器

这个项目是一个叉子 [`UPNG.js`](https://github.com/photopea/UPNG.js) 并创建用于 [`@adnsistemas/pdf-lib`](https://github.com/adnsistemas/pdf-lib)原雷波的维护者不向国家预防机制公布。 这是叉子的首要目的。 此外,一个 `index.d.ts` 文件已添加( 直接从 [`@types/upng-js`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/upng-js/index.d.ts))使TypeScript定义可用而无需安装额外包.  
原始软件包 [`@pdf-lib/upng`](https://github.com/Hopdig/upng) 进行了修改,以便能够将其用于无害环境管理和共同JS项目.

## 实例 `UPNG.toRGBA8`

```javascript
// Import the UPNG class
import UPNG from '@adnsistemas/upng';

// Create a UPNG object
const pngImage = UPNG.decode(/* Uint8Array containing bytes of PNG image */);

// `pixels` is a 1D array (in rgba order) of decoded pixel data
const pixels = pngImage.UPNG.toRGBA8();
```

## 安装

### 国家预防机制模块

要安装最新的稳定版本 :

```bash
# With npm
npm install --save @adnsistemas/upng

# With yarn
yarn add @adnsistemas/upng
```

这假设你用 [无](https://www.npmjs.com/) 或者说 [线条](https://yarnpkg.com/lang/en/) 作为您的包管理器.

### UMD 模块

您也可以下载 `@pdf-lib/upng` 作为UMD模块来自 [(单位:公斤)](https://unpkg.com/#/). UMD的建筑已经编译为ES5, 因此它们应该工作 [在任何现代浏览器中](https://caniuse.com/#feat=es5)。UMD 构建是有用的,如果你没有使用软件包管理器或模块捆绑器。 例如,您可以在 `<script>` 标记 HTML 页面.

以下建筑可供使用:

-   https://unpkg.com/@pdf-lib/upng/dist/UPNG.js
-   https://unpkg.com/@pdf-lib/upng/dist/UPNG.min.js (中文(简体) )

当您使用 UMD 架构时, 您将可访问全球 `window.UPNG` 变量。 此变量包含 `UPNG` 导出类别 `@pdf-lib/upng`。例如:

```javascript
// NPM module
import UPNG from '@pdf-lib/upng';
const pngImage = UPNG.decode(/* ... */)

// UMD module
var pngImage = window.UPNG.decode(/* ... */)
```

## 编码器

UPNG.js支持APNG,接口预期"帧". 常规PNG只是一款单帧动画(单项阵列).

#### `UPNG.encode(imgs, w, h, cnum, [dels], [tabs])`

-   `imgs`: 帧数组. 一个帧是一个包含像素数据的ArrayBuffer(RGBA,每道8位)
-   `w`, (中文(简体) ), `h` : 图像的宽度和高度
-   `cnum`: 结果中的颜色数; 0: 所有颜色( 无丢失的 PNG)
-   `dels`: 每个帧的毫秒延迟数组(仅在2个或更多帧时)
-   `tabs`: 选项的对象. `{ loop: 1 }` 将只播放一次动画( 默认为 `0`,将无限期地发挥.
-   返回带有 PNG 文件二进制数据的矩阵缓冲器

UPNG.js可以对PNG文件做一个丢失的微缩处理,类似于 [小型PNG](https://tinypng.com/) 和其他工具。 它进行了定量 [k 表示算法](https://en.wikipedia.org/wiki/K-means_clustering) 过去,但现在我们使用 [K-d 树](https://en.wikipedia.org/wiki/K-d_tree)。 。 。 .

上一个参数允许压缩丢失 `cnum`。设置为零进行无损压缩,或在图像中写入允许的颜色数量。 更小的值产生更小的文件. **或者只用0来表示无损失 / 256来表示有损失.**

```
// Read RGBA from canvas and encode with UPNG
var dta = ctx.getImageData(0,0,200,300).data;  // ctx is Context2D of a Canvas
//  dta = new Uint8Array(200 * 300 * 4);       // or generate pixels manually
var png = UPNG.encode([dta.buffer], 200, 300, 0);   console.log(new Uint8Array(png));
```

#### `UPNG.encodeLL(imgs, w, h, cc, ac, depth, [dels])` - 低级编码

-   `imgs`: 帧数组. 一个帧是一个包含像素数据的ArrayBuffer(对应以下参数)
-   `w`, (中文(简体) ), `h` : 图像的宽度和高度
-   `cc`, (中文(简体) ), `ac`: 彩色频道(1或3)和α频道(0或1)的数目
-   `depth`: 像素数据的位深(1, 2, 4, 8, 16)
-   `dels`: 每个帧的毫秒延迟数组(仅在2个或更多帧时)
-   返回带有 PNG 文件二进制数据的矩阵缓冲器

此函数不做任何优化, 它只是存储您给出的东西 。 有两种情况有用:

-   保存16位颜色(注:PNG是大底色,不同于JS中的Uint16Array)
-   您的图像太大了, 而“ 扩展” 到 8 位 RGBA 将使用过多的内存( 例如 4 位灰度 50,000 x 50,000 = 1. 25 GB, 8 位 RGBA 为 10 GB)

## 解码器

支持所有颜色类型(包括灰度和调色板),所有通道深度(1,2,4,8,16),相接图像等. 打开其他库无法打开的 PNG( 测试于 [套装](http://www.schaik.com/pngsuite/)) (中文(简体) ).

#### `UPNG.decode(buffer)`

-   `buffer`: 包含 PNG 文件的矩阵缓冲器
-   返回具有以下属性的图像对象:
-   -   `width`: 图像宽度
-   -   `height`: 图像的高度
-   -   `depth`: 每个频道的位数
-   -   `ctype`: 文件的颜色类型( Truecolor, 灰度, 调色板. )
-   -   `frames`: 有关帧的额外信息(帧延迟等)
-   -   `tabs`: PNG 文件的额外块
-   -   `data`: 图像的像素数据

PNG文件可能拥有多个频道并有不同的色彩深度. 解释: `data` 取决于当前颜色类型和颜色深度(参见 [PNG 规格](https://www.w3.org/TR/PNG/)) (中文(简体) ).

#### `UPNG.toRGBA8(img)`

-   `img`: PNG 图像对象(由 UPNG.decode () 返回)
-   返回框架阵列。 一个帧是以 RGBA 为格式的图像的矩阵缓冲器,每个通道有8位.

### 示例

```
var img  = UPNG.decode(buff);        // put ArrayBuffer of the PNG file into UPNG.decode
var rgba = UPNG.toRGBA8(img)[0];     // UPNG.toRGBA8 returns array of frames, size: width * height * 4 bytes.
```

PNG格式使用Inflate算法. 现在,UPNG.js打电话 [帕科(英语:Pako.js)](https://github.com/nodeca/pako) 以充电法和充电法发誓.

## 量子

UPNG.js包含一个非常好的由4个组件8位向量(即像素)组成的量子. 它可用于生成好彩色调色板(例如Photopea使用UPNG.js为GIF图像制作调色板).

量子化由两个重要步骤组成: 寻找一个漂亮的调色板和 寻找每个样本的调色板中最接近的颜色(大型调色板的非三角). UPNG从两个步骤.

```
var res  = UPNG.quantize(data, psize);
```

-   `data`: 样本的矩阵(字节长度为四倍)
-   `psize` : 调色板大小( 您想要多少颜色)

结果对象"res"具有以下属性: 1

-   `abuf`: 对应 `data`,用调色板重新映射颜色
-   `inds`: Uint8Array:每个样本的颜色索引(仅在 `psize`页:1
-   `plte`: 阵列:调色板 - 颜色列表, `plte[i].est.q` 财务报告和审定财务报表 `plte[i].est.rgba` 是颜色值

### 财务问题

-   要获得多个图像的常见调色板( 如动画的帧), 将它们合成一个阵列 `data`。 。 。 .
-   在使用少于4个组件时,将剩余组件设定为常数(例如为零)
-   在以透明方式工作时,通过透明方式预加多色元件(否则rgba(1,1,1,0)会更接近rgba(1,1,1)而接近rgba(0,0,0) - 以透明方式将透明地映射为白色而不是透明)

## 常见问题

### @adnsistemas/upng 是什么？

小型、快而先进的PNG/APNG编码和解码器

### 如何安装 @adnsistemas/upng？

在项目目录运行 npm install @adnsistemas/upng，或使用 pnpm add / yarn add / bun add。

### @adnsistemas/upng 支持 TypeScript 吗？

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

### @adnsistemas/upng 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @adnsistemas/upng 可以商用吗？

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

### @adnsistemas/upng 的下载量有多少？

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

### @adnsistemas/upng 还在维护吗？

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