# @blueprint-chart/lib 中文文档

规范地址：https://npmcn.com/package/%40blueprint-chart/lib/

版本：2\.15\.0
npm 元数据更新时间：2026-11-07T23:30:20.315Z
中文译文更新时间：2026-11-08T08:51:43.474Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.8 MB，166 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2026-05-14T22:26:03.367Z
- 最新版本发布：2026-11-07T23:30:19.991Z
- 近 30 天下载量：2713（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 65 个）

## 中文简介

DSL驱动的图表库以D3为基础. 将图表定义为正文,在任何地方将其变成正文.

## 安装

```sh
npm install @blueprint-chart/lib
```

也可以使用：`pnpm add @blueprint-chart/lib`、`yarn add @blueprint-chart/lib`、`bun add @blueprint-chart/lib`

## README

# @ 蓝印- 图表/ lib

蓝图图的核心库——一个由DSL驱动的以D3为主的绘图引擎.

## 安装

```bash
npm install @blueprint-chart/lib
```

## 快开始

### 节点 — 将 SVG 和 PNG 写入磁盘

```ts
import { render } from '@blueprint-chart/lib'
import { writeFile } from 'node:fs/promises'

const chart = await render(bpc)
await writeFile('chart.svg', await chart.toSvg())
await writeFile('chart.png', await chart.toPng({ width: 1200 }))
```

### 浏览器-挂载和步骤场景

```ts
const { mount, scene } = await render(bpc)
mount('#chart')   // element or selector
scene(2)          // advance to scene index 2
```

制作图表的最简单方式是IIFE运行时间,它自动扫描嵌入式图表定义的文档,并让每个文档内出一行(在脚本标记前插入一个沙盒内):

```html
<script src="https://unpkg.com/@blueprint-chart/lib/dist/lib/lib.iife.js"></script>

<script type="application/blueprint-chart">
  chart MyChart {
    data { values = "[[0,1],[1,4],[2,2]]" }
    series "line" { color = "steelblue" }
  }
</script>
```

对于一个ES模块项目中的程序用途,lib暴露了基础原始: `parse` (DSL —— AST), (中文(简体) ), `validateChart` (AST ) —— (韩语) `ValidationResult` 并打出错误和警告, `buildChartOptions` (AST-提供选择), `createFrame`编号 :`createCanvas`,和图表登记(`registerChart`, (中文(简体) ), `getChart`) (中文(简体) ). 见 [标准/指数.ts](https://github.com/blueprint-chart/blueprint-chart/blob/main/packages/lib/src/index.ts) 完全公开API.

## DSL 语法

图表 DSL 是由 PEG 语法定义的 `src/dsl/grammar.peggy` 并编入 `src/dsl/grammar.js` 使用 [佩吉](https://peggyjs.org/)。 。 。 .

### EBNF 概览

```
Chart       = "chart" Identifier "{" ChartMember* "}"
ChartMember = DataBlock | Colorize | AreaFill | Annotation | Series | Scene | Property

DataBlock   = "data" "{" Property* "}"
Colorize    = "colorize" String "{" Property* "}"
AreaFill    = "area-fill" String String "{" Property* "}"
Annotation  = "annotation" String "{" Property* "}"
Series      = "series" String "{" Property* "}"
Scene       = "scene" String "{" SceneMember* "}"
SceneMember = DataBlock | Colorize | AreaFill | Annotation | Property

Property    = PropertyKey "=" PropertyValue
PropertyKey = String | Identifier
PropertyValue = Number "%" | Number | String | Identifier

Identifier  = [a-zA-Z_#][a-zA-Z0-9_#-]*
Number      = [0-9]+("."[0-9]+)?
String      = '"' (EscapeSequence | [^"\\])* '"'
```

### 示例

```
chart horizontal-bar {
  title = "Revenue by Region"
  sort = descending

  data {
    "North America" = 75%
    "Europe" = 53.85%
    "Asia" = 44%
  }

  colorize "North America" {
    color = "#e53e3e"
    label = "Leader"
  }

  scene "Focus" {
    sort = ascending
    colorize "Asia" {
      color = "#38a169"
    }
  }
}
```

## AST 节点类型

| 节点 | 字段 |
| --- | --- |
| `ChartNode` | `chartType`, (中文(简体) ), `properties`, (中文(简体) ), `data`, (中文(简体) ), `colorizes`, (中文(简体) ), `areaFills`, (中文(简体) ), `annotations`, (中文(简体) ), `series`, (中文(简体) ), `scenes` |
| `PropertyNode` | `key`, (中文(简体) ), `value`, (中文(简体) ), `isPercentage` |
| `DataNode` | `entries` (财产节点\[\]) |
| `ColorizeNode` | `target`, (中文(简体) ), `properties` |
| `AreaFillNode` | `from`, (中文(简体) ), `to`, (中文(简体) ), `properties` |
| `AnnotationNode` | `target`, (中文(简体) ), `properties` |
| `SeriesNode` | `name`, (中文(简体) ), `properties` |
| `SceneNode` | `name`, (中文(简体) ), `properties`, (中文(简体) ), `data`, (中文(简体) ), `colorizes`, (中文(简体) ), `areaFills`, (中文(简体) ), `annotations` |

## 再生成解析器

生成的解析器( E)`src/dsl/grammar.js`) 被检查为 git ,所以下游包可以直接导入 lib 源而无需构建步骤 .

编辑后重生 `grammar.peggy`数字 :

```sh
pnpm --filter @blueprint-chart/lib run generate:parser
```

此功能也在前自动运行 `build` 财务报告和审定财务报表 `test` 通过 `prebuild`编号 :`pretest` 钩子.

## 颜色调色板

内置的调色板从 [催眠药](https://github.com/y-sunflower/pypalettes) 由Joseph Music所收录,为数据可视化所收录的2700+彩色调色板. 根据麻省理工学院的许可.

## 常见问题

### @blueprint-chart/lib 是什么？

DSL驱动的图表库以D3为基础\. 将图表定义为正文,在任何地方将其变成正文\.

### 如何安装 @blueprint-chart/lib？

在项目目录运行 npm install @blueprint-chart/lib，或使用 pnpm add / yarn add / bun add。

### @blueprint-chart/lib 支持 TypeScript 吗？

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

### @blueprint-chart/lib 支持 ESM 还是 CommonJS？

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

### @blueprint-chart/lib 可以商用吗？

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

### @blueprint-chart/lib 的下载量有多少？

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

### @blueprint-chart/lib 还在维护吗？

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