# @cssints/placeholder 中文文档

规范地址：https://npmcn.com/package/%40cssints/placeholder/

版本：0\.35\.1
npm 元数据更新时间：2026-11-07T14:55:40.779Z
中文译文更新时间：2026-11-11T03:42:17.984Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cssints/placeholder
原文对照：https://npmcn.com/package/%40cssints/placeholder/?lang=original
项目主页：https://cssints.dev/
源码仓库：https://github.com/alexeiaccio/css-in-ts-compiler

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

- 包体积（解压后）：15.4 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- peer 依赖：cssints ^0\.35\.0
- 首次发布：2026-10-10T20:57:56.489Z
- 最新版本发布：2026-11-07T14:55:40.434Z
- 近 30 天下载量：7379（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

Csints 的图像占位符:主色调的梯度,或缩略图数据 URL,从构建时的图像读取

## 安装

```sh
npm install @cssints/placeholder
```

也可以使用：`pnpm add @cssints/placeholder`、`yarn add @cssints/placeholder`、`bun add @cssints/placeholder`

## README

# @ cssints/ 占位符

图像占位符用于 [点缀](https://npmcn.com/package/README.md)数字 : `placeholder(path)` 当构建运行和给出图像时, 读取图像 `<image>` 画到真实的负载, 要么是图像颜色的渐变 或图像的 [缩略图](https://evanw.github.io/thumbhash/) 作为一个微小的PNG数据 URL (中文(简体) ). 它是一个价值成员 `cssints/plugin` `scope()`因此它进入 `backgroundImage` (或 `maskImage`) (中文(简体) ). 没有运行时间.

```ts
import { backgroundImage, cn, backgroundSize } from "cssints" with { type: "cssints" };
import { placeholder } from "@cssints/placeholder" with { type: "cssints" };

// placeholder(path, { mode? }): the path is relative to the working directory
export const hero = backgroundImage(placeholder("src/hero.jpg"));
export const card = cn(
  backgroundImage(placeholder("src/card.png", { mode: "thumbhash" })),
  backgroundSize("cover"),
);
```

对于由四个四角(红、蓝、绿、白)组成的PNG:

```css
/* mode "gradient" (the default): a 4 × 3 grid, a radial gradient per cell, brightest on top, over the average colour */
._11mb38d {
  background-image:
    radial-gradient(at 67% 100%, #ffffff, transparent 50%),
    radial-gradient(at 100% 100%, #ffffff, transparent 50%),
    radial-gradient(at 67% 50%, #bcbcff, transparent 50%),
    /* … one per cell, 12 in all … */ radial-gradient(at 100% 0, #0000ff, transparent 50%),
    linear-gradient(#bc96bc, #bc96bc);
}
/* mode "thumbhash": the ThumbHash rendered, 16 px on the long side, about 0.5 kB */
._179cifn {
  background-image: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAM…");
}
```

## 格式

JPEG( 基线和渐进式, 通过 [日语](https://github.com/jpeg-js/jpeg-js))和 PNG(每个颜色类型和位 深度,通过 [弹簧](https://github.com/pngjs/pngjs)),两个平版JavaScript:没有编译,没有本地二进制 (正字未用). 格式从文件的第一个字节来读取,而不是它的名字. WebP、AVIF、GIF和SVG正在建设 命名格式的错误( e)`cssints: placeholder: src/hero.webp: a WebP image: JPEG and PNG are read`: 给出 JPEG 或 PNG 复制的图像( 它可以是小的; 只有它的颜色被读取) .

## 规则

-   **辩相.** `path` 是一个字符串,相对于工作目录(`process.cwd()`,维特下的项目根, 作为 `fs` 供应商 `@cssints/icons` 读它. `mode` 实值 `"gradient"` (默认)或 `"thumbhash"`两者都是 检查类型和建设时间.
-   **`gradient`** 以线性光线和加权表示的4×3个单元格(3×4个肖像图像)的网格平均图像 由alpha,所以一个透明的部分不增加颜色,一个横跨红色和绿色的细胞是光的混合体,而不是泥地 sRGB平均值. 每个单元格都是 `radial-gradient(at x y, colour, transparent 50%)` 在图像中的位置 `0` 财务报告和审定财务报表 `100%`),由最亮的上方(如不显出位置者)所排序 `linear-gradient()` 表示整个图像的平均颜色,以填补梯度所留下的颜色。 一个不透明的单元格 实值 `#rrggbbaa`。值是13个图像的列表,大约为0.7 kB.
-   **`thumbhash`** 用缩略图编码图像( 平均最多100 px a side first), 使散列, 平均值 写成PNG:约0.5 kB,其中ThambHash自己的数据URL(32 px, 未压缩)约为5克B. 浏览器的平滑提升会模糊. 它保持了宽度比,所以它与 `backgroundSize("cover")` 或者说 `"100% 100%"`。 。 。 .
-   **决取相取.** 同样的文件在每一个构建上都给出相同的CSS. SHA-256对结果进行缓存 文件的内容和模式,所以从许多模块中使用的图像会被解码一次.
-   **错误**,在调用时:无法读取的文件(`cssints: placeholder: cannot read src/nope.png (paths are relative to /app)`),它不读取的格式(上),不解码的文件(`cssints: placeholder: src/broken.png: …`,解码器的信息),语法以外的一种模式(`placeholder(2).mode: unexpected "blurhash" …`),以及图像不走的占位符(`css.color(placeholder(…))`,在类型和构建时出错 时间).

## 限制

-   在dev中,一个被编辑的图像更新了使用它的模块的CSS(`dependsOn` 联 合 国 `cssints/plugin`); 缺少图像 在构建错误后添加,需要编辑模块或重新加载.
-   这个 `gradient` 值是一个图像列表,因此它符合一个需要列表的属性(`background-image`, (中文(简体) ), `mask-image`(三); 拥有一项的财产 `<image>` (单位:千美元)`list-style-image`, (中文(简体) ), `border-image-source`() 在建设时拒绝:使用 `thumbhash` 在这里.
-   没有WebP或AVIF解码器(一个WASM 1会给建筑增加几百 kB);网格大小和缩略图大小是 固定; 无模糊模式 .
-   图像被解码为整体:一个非常大的JPEG(十兆像素)每建造一次,其像素在内存中花费.

```bash
cd packages/placeholder && bun run test        # colour extraction on synthetic pixels, fixtures through the engine (output, errors)
cd packages/placeholder && bun run typecheck   # and the type test, test/types/placeholder.ts
```

## 贷项

梯度布局如下 [未选占位符](https://github.com/ascorbic/unpic-placeholder) (麻省理工学院,Matt Kane). 缩略图模式使用 [缩略图](https://github.com/evanw/thumbhash) (麻省理工,埃文·华莱士), [日语](https://github.com/jpeg-js/jpeg-js) (BSD-3-Clause)和 [弹簧](https://github.com/pngjs/pngjs) (麻省理工学院),属地. 没有复制代码 .

## 常见问题

### @cssints/placeholder 是什么？

Csints 的图像占位符:主色调的梯度,或缩略图数据 URL,从构建时的图像读取

### 如何安装 @cssints/placeholder？

在项目目录运行 npm install @cssints/placeholder，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：cssints（^0\.35\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cssints/placeholder 支持 TypeScript 吗？

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

### @cssints/placeholder 支持 ESM 还是 CommonJS？

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

### @cssints/placeholder 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cssints/placeholder 可以商用吗？

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

### @cssints/placeholder 的下载量有多少？

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

### @cssints/placeholder 还在维护吗？

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