# @d3fc/d3fc-label-layout 中文文档

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

版本：7\.0\.4
npm 元数据更新时间：2024-06-13T14:55:09.599Z
中文译文更新时间：2026-11-11T08:06:45.439Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：236 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：d3-array \*，d3-scale \*，d3-selection \*
- 首次发布：2018-08-02T13:52:33.190Z
- 最新版本发布：2024-06-13T14:55:09.384Z
- 近 30 天下载量：62529（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 0 个）

## 中文简介

D3 版式, 使用贪婪或模拟反射策略放置避免重叠的标签

## 安装

```sh
npm install @d3fc/d3fc-label-layout
```

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

## README

# d3fc-标签放出

一种D3布局,将标签放置在避免重叠的地方,其策略包括模拟的取暖,贪婪和去除重叠标签的策略.

![](https://npmcn.com/package/%40d3fc/d3fc-label-layout/screenshots/d3fc-label-layout.png)

现场演示请看 [GitHub 页面网站](http://d3fc.github.io/d3fc-label-layout/)。 。 。 .

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

## 安装

```bash
npm install @d3fc/d3fc-label-layout
```

## API 参考

-   [标签](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-label)
-   [战略](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-strategy)
-   [文本标签](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-text-label)
-   [战略](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-strategy)

标签布局组件提供了基于其长方形边框排列子组件的机制. 它通常用于在地图或图表上渲染标签. 将布局策略传递给组件,以便安排子矩来避免相撞或去除相重叠.

```javascript
import { layoutTextLabel, layoutGreedy,
    layoutLabel, layoutRemoveOverlaps } from 'd3fc-label-layout';
import { select } from 'd3-selection';

const labelPadding = 2;

// the component used to render each label
const textLabel = layoutTextLabel()
  .padding(labelPadding)
  .value(d => d.properties.name);

// a strategy that combines simulated annealing with removal
// of overlapping labels
const strategy = layoutRemoveOverlaps(layoutGreedy());

// create the layout that positions the labels
const labels = layoutLabel(strategy)
    .size((d, i, g) => {
        // measure the label and add the required padding
        const textSize = g[i].getElementsByTagName('text')[0].getBBox();
        return [textSize.width + labelPadding * 2, textSize.height + labelPadding * 2];
    })
    .position(d => projection(d.geometry.coordinates))
    .component(textLabel);

// render!
svg.datum(places.features)
     .call(labels);
```

以上片段取自一个完整的例子,说明如何 [标签布局组件可用于在地图上排列标签](http://bl.ocks.org/ColinEberhardt/389c76c6a544af9f0cab)。 。 。 .

为了与图表合并,标签布局组件将曝光 `xScale` 财务报告和审定财务报表 `yScale` 属性,作为 [在此示例中显示](https://bl.ocks.org/ColinEberhardt/27508a7c0832d6e8132a9d1d8aaf231c/a49aac43f1bd770506dc3660aba149193f7def8b)。 。 。 .

### 标签

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutLabel) 页:1.**布局标签**(单位:千美元)_战略_(中文(简体) )

构造新标签布局 _战略_。标签布局将创建一系列矩形边框,这些边框将传递给策略,通常会移动框以尽量减少重叠。 一旦布局完成,将使用数据连接来构建一个包含 `g` 框中每个项的元素,向布局提供的组件被“调用”-“调用”.

每个 `g` 元素有以下属性集:

-   `layout-width`, (中文(简体) ), `layout-height` - 该标签的宽度和高度,由 `size` 属性.
-   `display` - 准备 `inherit` 或者说 `hidden`,基于策略是否隐藏了此标签.
-   `anchor-x`, (中文(简体) ), `anchor-y` - 相对于坐标的原始标签位置 `g` 键.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutLabel_size) _布局标签_。 。 。 .**大小**(单位:千美元)_访问器_(中文(简体) )

指定相关阵列中每个项目的大小。 这个 _访问器_ 函数被精确引用一次,并应当返回大小为两个值的数组, `[width, height]`编辑 _访问器_ 函数与当前基准(d)、当前索引(一)和当前组(节点)一起引用。 此函数在组件提供后被引用,且其值为 _这个_ 上下文是包含 `g` 键。 因此,如果内容是动态的,可以测量组件的大小,例如,测量文本标签的大小.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutLabel_position) _布局标签_。 。 。 .**职位**(单位:千美元)_访问器_(中文(简体) )

指定关联数组中每个项目的位置。 这个 _访问器_ 函数被精确引用一次,并带有当前基准(d),当前索引(一)和当前组(节点),并且应当将位置作为由两个值组成的数组返回, `[x, y]`。 。 。 .

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutLabel_component) _布局标签_。 。 。 .**组件**(单位:千美元)_组件_(中文(简体) )

指定用于制取每个标签的组件.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutLabel_xScale) _布局标签_。 。 。 .**十. 规模**(单位:千美元)_缩放_(中文(简体) ) [{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutLabel_yScale) _布局标签_。 。 。 .**比例**(单位:千美元)_缩放_(中文(简体) )

若为 _缩放_ ,设置比例并返回标签布局组件。 若为 _缩放_ 未指定,返回当前比额表.

比额表适用于每个项目的位置,即:. `[x, y] -> [xScale(x), yScale(y)]`,默认比例表为身份.

### 战略

标签组件使用策略来重新定位标签来避免相撞,或者也许隐藏重叠的标签.

战略提供一系列物体,说明每个标签的初始位置 `position` 财务报告和审定财务报表 `size` 属性 `layout`。 。 。 .

每个天体的结构如下:

```
{
    hidden: ...,
    x: ...,
    y: ...,
    width: ...,
    height: ...,
}
```

策略应返回显示每个标签位置的一系列对象.

#### 贪婪

贪婪的策略是减少标签重叠的非常快的方法. 它按顺序添加了每个标签,选择标签与已经添加的矩形重叠最小的位置,并在容器内.

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

构建出一种贪婪的策略.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutGreedy_bounds) _布局风格_。 。 。 .**边框**(单位:千美元)_矩形_(中文(简体) )

可选择指定一个边界区域,作为具有以下特性的矩形: `x`, (中文(简体) ), `y`, (中文(简体) ), `width` 财务报告和审定财务报表 `height`。策略将试图将标签限制在限度内.

#### 模拟 Annaling

模拟的厌战策略贯穿了一组迭代,为每个迭代上的一个标签选择了不同的位置. 如果该位置能产生更好的结果,则保存到下一次重复。 否则,其保存概率将与其目前的迭代成反比。 这有助于打破当地的最佳条件,希望能够产生更好的产出。 由于算法的随机性,它会产生可变输出.

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

构造出一个反射策略.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutAnnealing_bounds) _排程_。 。 。 .**边框**(单位:千美元)_矩形_(中文(简体) )

可选择指定一个边界区域,作为具有以下特性的矩形: `x`, (中文(简体) ), `y`, (中文(简体) ), `width` 财务报告和审定财务报表 `height`。策略将试图将标签限制在限度内.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutAnnealing_temperature) _排程_。 。 。 .**温度**(单位:千美元)_整数_(中文(简体) )

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutAnnealing_cooling) _排程_。 。 。 .**冷却**(单位:千美元)_整数_(中文(简体) )

这个 _温度_ 参数表示用于随机概率计算的初始“数”,以及 _冷却_ 定义迭代之间温度的三角洲。 算法运行于 `Math.ceil(temperature / cooling)` 迭相会.

#### 删除重叠

这种策略不会为减少重叠而重新定位标签,而是去除重叠的标签. 这是反复进行的,首先去掉重叠面积最大的标签.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutRemoveOverlaps) 页:1.**重新移动重叠**(单位:千美元)_战略_(中文(简体) )

构造一个去除重叠策略, 并调整所提供的策略 _战略_ 以便消除执行后重叠.

### 文本标签

这是一个简单的组件,使标签:

![](https://npmcn.com/package/%40d3fc/d3fc-label-layout/screenshots/textLabel.png)

此组件使用 `layout-width` 财务报告和审定财务报表 `layout-height` 属性,用于设定自己的宽度和高度。 它也使用 `anchor-x` 财务报告和审定财务报表 `anchor-y` 属性以放置圆形锚地。 这些属性均由上述标签布局设置.

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

构造文本标签组件.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-textLabel_labelPadding) _文本标签_。 。 。 .**标签**(单位:千美元)_编号_(中文(简体) )

指定文本周围的粘贴.

[{\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0}](https://npmcn.com/package/%40d3fc/d3fc-label-layout/#readme-layoutTextLabel_value) _外观标签_。 。 。 .**价值**(单位:千美元)_访问器_(中文(简体) )

指定此标签的文本为访问器函数.

## 常见问题

### @d3fc/d3fc-label-layout 是什么？

D3 版式, 使用贪婪或模拟反射策略放置避免重叠的标签

### 如何安装 @d3fc/d3fc-label-layout？

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

### @d3fc/d3fc-label-layout 支持 TypeScript 吗？

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

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

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

### @d3fc/d3fc-label-layout 可以商用吗？

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

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

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

### @d3fc/d3fc-label-layout 还在维护吗？

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