# bookcover-web 中文文档

规范地址：https://npmcn.com/package/bookcover-web/

版本：0\.24\.0
npm 元数据更新时间：2026-11-03T04:33:31.625Z
中文译文更新时间：2026-11-03T06:06:07.914Z
软件包许可：MIT-0

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

原始 npm 页面：https://www.npmjs.com/package/bookcover-web
原文对照：https://npmcn.com/package/bookcover-web/?lang=original
项目主页：https://github.com/gracious-tech/bookcover/tree/main/generator-web#readme
源码仓库：https://github.com/gracious-tech/bookcover

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

- 包体积（解压后）：53.6 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-07-16T12:01:56.983Z
- 最新版本发布：2026-11-03T04:33:31.460Z
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

生成印刷就绪的书籍封面。部分 [封套](https://github.com/gracious-tech/bookcover) 一代系统。

## 安装

```sh
npm install bookcover-web
```

也可以使用：`pnpm add bookcover-web`、`yarn add bookcover-web`、`bun add bookcover-web`

## README

# bookcover-web

生成印刷就绪的书籍封面。部分 [封套](https://github.com/gracious-tech/bookcover) 一代系统。

```
npm install bookcover-web
```

[![Example cover](https://npmcn.com/package/sample.svg)](https://npmcn.com/package/sample.pdf "View example PDF")

这是图书封面生成器的浏览器包装器。它使用WASM编译覆盖 [typst.ts](https://github.com/Myriad-Dreamin/typst.ts).

## 看到 [模式参考](https://github.com/gracious-tech/bookcover/blob/main/generator/README.md) 这是作为参数传递的，它实际上配置了封面设计。

```ts
import {init, CoverGenerator} from 'bookcover-web'
```

## `init(options): Promise<CoverGenerator>`

使用初始化的WASM编译器和可选的呈现器创建生成器实例。

```ts
interface InitOptions {
    wasm_url: string              // URL to typst_ts_web_compiler_bg.wasm
    renderer_wasm_url?: string    // URL to typst_ts_renderer_bg.wasm (required for SVG/PNG)
    assets_prefix?: string        // URL prefix for static assets (templates, frames, backgrounds)
    fonts_prefix?: string         // URL prefix for the fonts tree (manifest.json + families)
}
```

## 资产

Typst模板被捆绑在里面 `bookcover-core` 本身（绑到确切的安装） 版本-不需要设置)。生成仍然在运行时获取三种资源，没有 在npm包中包含：WASM二进制文件、frame images (`frames/`)，以及字体 树。最简单的设置是托管树 `https://assets.paper.bible/` (歌珥启用):

> 这个 `typst/` WASM二进制文件以brotli压缩方式存储并提供 `Content-Encoding: br` 每个客户端，没有内容协商-编译器是27 MB raw格式和6.9 MB压缩文件，所以这不是可选的。浏览器可以透明地处理它。如果你 从非浏览器客户端获取这些，确保它可以解码 `br` （`curl` 需要 `--compressed`， 或者将压缩字节写入磁盘)。

```ts
// Match the wasm version to your installed @myriaddreamin/typst-ts-web-compiler version
const typst_version = '0.7.0'

const generator = await init({
    wasm_url: `https://assets.paper.bible/typst/${typst_version}/typst_ts_web_compiler_bg.wasm`,
    renderer_wasm_url: `https://assets.paper.bible/typst/${typst_version}/typst_ts_renderer_bg.wasm`,
    assets_prefix: 'https://assets.paper.bible/',
    fonts_prefix: 'https://assets.paper.bible/fonts',
})
```

而要使用self-host，请在origin上的任何前缀下提供相同的布局：

-   **WASM** -使用Vite，直接从安装的包中导入url（没有托管） 需要): `import wasm_url from '@myriaddreamin/typst-ts-web-compiler/pkg/typst_ts_web_compiler_bg.wasm?url'` (同样 对于渲染器)。没有捆绑器，从 `node_modules` 到你的 `public/` dir。
    
-   **`<assets_prefix>/frames/`** - - - - - - `painted.png` 和 `torn.png`从回购文件中抄来的 `assets/frames/`． （`backgrounds/` 仅当您的UI提供建议时才需要 背景图片-见下文。)
    
-   **`<fonts_prefix>/`** -字体树(`manifest.json`每户一人，不得有退路 下 `_noto/`）. 使用repo的字体配置生成它：
    
    ```bash
    curl -O https://raw.githubusercontent.com/gracious-tech/bookcover/main/font_config.json
    npx typst-fonts-download --fonts public/fonts --config font_config.json
    ```
    

### 内置的背景

内置背景文件的文件名(例如： `beach.jpg`)是它的ID——嵌入协议发送一个内置的 作为 `bg_image_builtin` 没有字节。将其连接到其中任何一个以获取副本：

-   `https://assets.paper.bible/backgrounds/<name>` -最终版本的原版（平均2.8MB） 输出
-   `https://assets.paper.bible/backgrounds/previews_2700/<name>` （`BG_PREVIEW_DIR`) - ~ 380kb， 足以在屏幕上预览一个6x9”的封面
-   `https://assets.paper.bible/backgrounds/previews_800/<name>` -大缩略图
-   `https://assets.paper.bible/backgrounds/thumbnails/<name>` - 160x120拾荒砖

将文件名传递给 `generate()` 作为 `image_builtin` 无论你渲染哪个副本，都是自动的 文本颜色来自其烘烤的颜色数据，预览与最终输出完全匹配。 `get_builtin_bg_regions(name)` 返回相同的数据，和 `get_builtin_bg(name)` 添加了 原始像素大小（用于分辨率检查而无需下载）。

## `CoverGenerator.generate(options): Promise<GenerateResult>`

```ts
interface GenerateOptions {
    schema: unknown               // raw schema (see above)
    image?: Blob                  // background image
    // Filename of the built-in background `image` is a copy of — colors come from its baked data
    image_builtin?: string
    // Shrink `image` to at most this many pixels per inch of cover before compiling (previews)
    image_max_dpi?: number
    format?: 'pdf'|'svg'|'png'   // default: 'pdf'
    ppi?: number                  // PNG resolution, default: 144
    split?: boolean               // include split panels in result
    pdf_pages?: boolean           // PDF: front and back pages (no spine), bleed all round
    custom_fonts?: Uint8Array[]   // raw TTF bytes for custom fonts
}

interface GenerateResult {
    data: Uint8Array | string     // full cover (bytes for PDF/PNG, string for SVG)
    split?: SplitResult<Uint8Array> | SplitResult<string>
}
```

## `CoverGenerator.destroy()`

撤销blob url以释放内存。当不再需要实例时调用。

### 例子

```ts
import {init} from 'bookcover-web'

const generator = await init({
    wasm_url: 'https://assets.paper.bible/typst/0.7.0/typst_ts_web_compiler_bg.wasm',
    renderer_wasm_url: 'https://assets.paper.bible/typst/0.7.0/typst_ts_renderer_bg.wasm',
    assets_prefix: 'https://assets.paper.bible/',
    fonts_prefix: 'https://assets.paper.bible/fonts',
})

const result = await generator.generate({
    schema: {title1: 'My Book', author: 'Jane Doe', /* ... */},
    format: 'svg',
    split: true,
})

// result.data is the full SVG string
// result.split.front / .back / .spine are individual panel SVGs
```

## 常见问题

### bookcover-web 是什么？

生成印刷就绪的书籍封面。部分 封套 一代系统。

### 如何安装 bookcover-web？

在项目目录运行 npm install bookcover-web，或使用 pnpm add / yarn add / bun add。

### bookcover-web 支持 TypeScript 吗？

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

### bookcover-web 支持 ESM 还是 CommonJS？

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

### bookcover-web 可以商用吗？

bookcover-web 使用 MIT-0 许可。声明的许可为 MIT-0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### bookcover-web 还在维护吗？

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