# @d3fc/d3fc-brush 中文文档

规范地址：https://npmcn.com/package/%40d3fc/d3fc-brush/

版本：3\.0\.3
npm 元数据更新时间：2022-04-05T02:30:52.919Z
中文译文更新时间：2026-11-11T08:10:07.114Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：37.1 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：d3-brush \*，d3-dispatch \*，d3-scale \*，d3-selection \*
- 首次发布：2018-08-02T13:52:45.535Z
- 最新版本发布：2020-09-23T20:32:03.731Z
- 近 30 天下载量：61555（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：95（近 12 个月 0 个）

## 中文简介

适应了D3刷子,更容易创建由数据驱动的刷子图.

## 安装

```sh
npm install @d3fc/d3fc-brush
```

也可以使用：`pnpm add @d3fc/d3fc-brush`、`yarn add @d3fc/d3fc-brush`、`bun add @d3fc/d3fc-brush`

## README

# d3fc-笔刷

适应了D3刷子,更容易地创建出由数据驱动,反应快的刷子图.

![](https://d3fc.io/examples/brush-navigator/screenshot.png)

[主要 D3FC 软件包](https://github.com/d3fc/d3fc)

## 安装

```bash
npm install @d3fc/d3fc-brush
```

## API 参考

### API 概况

D3fc-brush 组件将修改 [d3-笔刷](https://github.com/d3/d3-brush)实现以下目标:

1.  D3fc-brush由数据驱动,由通过数据加合提供的数据确定刷子的位置. 这样可以更容易地创建具有响应性的图表(即支持再缩放),与其他交互式组件如缩放相融合,并创建具有一能性的图表渲染逻辑.
2.  D3fc-brush 曝光 `xScale` 财务报告和审定财务报表 `yScale` 属性,用于与 [多号编](https://github.com/d3fc/d3fc/tree/master/packages/d3fc-series#multi-series) 构成部分和 [笛卡尔图](https://github.com/d3fc/d3fc/tree/master/packages/d3fc-chart#cartesian) 组件。 因此,根据每个轴的射程自动设定了刷子的范围.
3.  D3fc-刷子选择(定义了刷子范围),以百分比表示,而d3-刷子使用像素. 使用百分数选择可以更容易地调整刷图大小.
4.  刷子事件暴露了根据当前选择计算轴域的公用功能,使得处理刷子事件和更新图表更加容易.

### 创建导航图

刷子的一个常见应用是创建两个相连接的图表,一个起到"导航"的作用,允许用户在某个特定数据区域上放大. 此示例的完整代码见 `examples` 文件夹.

D3FC刷由数据驱动,因此第一步是创建数据对象,将标准序列数据与指定刷位置的范围相合并:

```javascript
var chartData = {
    series: data,
    brushedRange: [0, 1]
};
```

D3FC刷使用与D3刷相同的数据格式:

> 对于二维画笔,是\[\[x0,y0\],\[x1,y1\]\],其中x0为最小x-值,y0为最小y-值,x1为最大x-值,y1为最大y-值. 对于一个x-刷子,是\[x0,x1\];对于一个y-刷子,是\[y0,y1\].

一个多系列可以用来将刷子和另一个系列结合,例如一个区域系列:

```javascript
var brush = fc.brushX();

var multi = fc.seriesSvgMulti()
    .series([area, brush])
    .mapping((data, index, series) => {
        switch (series[index]) {
        case area:
            return data.series;
        case brush:
            return data.brushedRange;
        }
    });
```

主图和航海图使用笛卡尔图组件提供,航海图使用上文定义的多系列:

```javascript
var mainChart = fc.chartCartesian(x, y)
    .svgPlotArea(area);

var navigatorChart = fc.chartCartesian(x.copy(), y.copy())
    .svgPlotArea(multi);

function render() {
    d3.select('#main-chart')
        .datum(chartData.series)
        .call(mainChart);

    d3.select('#navigator-chart')
        .datum(chartData)
        .call(navigatorChart);
}

render();
```

最后一步是在刷子上添加事件处理器. 该事件连同 `xDomain` 财务报告和审定财务报表 `yDomain` 属性设置为刷新区域所代表的域.

事件处理器只是将数据"绑定"更新到图表,以反映新的选择并更新主图表的域. 由于这些图表具有一分能和数据驱动性,剩下的只是援引 `render` 函数.

```javascript
var brush = fc.brushX()
    .on('brush end', function(evt) {
        chartData.brushedRange = evt.selection;
        x.domain(evt.xDomain);
        render();
    });
```

如果您想要启用刷子, 使其不占据整个范围 `[0, 1]`,您需要设置主图的初始域. 可以通过使用一个具有相同域和单位范围的尺度来实现:

```javascript
var scale = d3.scaleLinear().domain(x.domain());
x.domain(chartData.brushedRange.map(scale.invert));
```

### 笔刷

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-brush/#readme-brush) 页:1.**刷头**(a) 与《公约》有关的其他事项

创建一个新的二维刷子.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-brush/#readme-brushX) 页:1.**刷新X**(a) 与《公约》有关的其他事项

沿着 x-dimension 创建一维刷.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-brush/#readme-brushY) 页:1.**画笔Y**(a) 与《公约》有关的其他事项

沿 Y-dimension 创建一维刷子 .

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-brush/#readme-on) _刷头_。 。 。 .**打开**(单位:千美元)_类型名称_, (中文(简体) ), _\[听众\]_(中文(简体) )

为指定事件类型添加事件倾听器, 参见 [调度. on](https://github.com/d3/d3-dispatch#dispatch_on) 详细情况。 这个 _类型_ 必须是下列情况之一:

-   `start` - 在刷子手势的起步,比如鼠标倒下.
-   `brush` - 当刷子移动,例如鼠标移动.
-   `end` - 在刷子手势的结尾,比如鼠标.

事件对象暴露出以下字段:

-   `selection` - 最新选择.
-   `xDomain` - 指定选择所代表的x域.
-   `yDomain` - 指定选择所代表的y域.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-brush/#readme-xScale) _刷头_。 。 。 .**十. 规模**(单位:千美元)_缩放_(中文(简体) ) [{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-brush/#readme-yScale) _刷头_。 。 。 .**比例**(单位:千美元)_缩放_(中文(简体) )

若为 _缩放_ 指定,设置比例并返回此刷子。 若为 _缩放_ 未指定,返回当前比额表.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-brush/#readme-filter) _刷头_。 。 。 .**过滤器**(单位:千美元)_\[过滤_(中文(简体) )

见d3-刷子 [过滤器](https://github.com/d3/d3-brush#brush_filter)。 。 。 .

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-brush/#readme-filter) _刷头_。 。 。 .**手柄大小**(单位:千美元)_\[大小\]_(中文(简体) )

见d3-刷子 [手柄大小](https://github.com/d3/d3-brush#brush_handleSize)。 。 。 .

## 常见问题

### @d3fc/d3fc-brush 是什么？

适应了D3刷子,更容易创建由数据驱动的刷子图\.

### 如何安装 @d3fc/d3fc-brush？

在项目目录运行 npm install @d3fc/d3fc-brush，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：d3-brush（\*）、d3-dispatch（\*）、d3-scale（\*）、d3-selection（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @d3fc/d3fc-brush 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/d3fc\_\_d3fc-brush 是否存在。

### @d3fc/d3fc-brush 支持 ESM 还是 CommonJS？

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

### @d3fc/d3fc-brush 可以商用吗？

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

### @d3fc/d3fc-brush 的下载量有多少？

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

### @d3fc/d3fc-brush 还在维护吗？

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