D3.js 4.x API中文手册

本文档会随官方文档同步更新。

说说4.x

今天（2016-05-14）打开D3的项目地址https://github.com/d3/d3 ，发现描述已经变成了：

Bring data to life with SVG, Canvas and HTML

比以前多个了Canvas，也就是说D3.js的历史进入了新纪元。这是历经早期Protovis只支持SVG到后来d3.v3支持HTML操作，如今又进入了一个崭新的阶段将支持Canvas了。d3.v4的源码也有相当大的调整，最明显的是分成了很多小模块单独开发。模块化开发果然和预想的一样是要为支持Canvas做准备，这确实是一件让人热血澎湃的好事。D3留给我们的想象空间还很大。好吧，为了更好地拥抱新技术！本项目将通过对D3 V4官方文档的翻译对d3.v4做个全面深入的了解。本文为保持原汁原味，会采用直译，希望成为帮助大家入门d3.v4的第一手资料。

题外话

如果大家想在官方博客发文章可以参考：http://blockbuilder.org/

如果想检索4.x的案例可以参考：http://blockbuilder.org/search#d3version=v4

4.x的新功能

颜色，插值器，比例尺

颜色有透明度（rgba，hsla等）。
新增Cubehelix颜色空间。
新增连续型颜色比例尺：绿松石（Viridis）和周期性的彩虹（cyclical Rainbow）。
新增点比例尺和段比例尺替代以前的ordinal.rangeBands和ordinal.rangePoints。
新增基本样条曲线插值器（例如连续的ColorBrewer）。

形状和布局。

形状支持渲染成Canvas。
修复了cardinal 和 monotone样条曲线。
增加了参数化的 Catmull–Rom 和natural样条曲线。
新的确定，可扩展的速度Verlet力布局。
新的圆形填充布局。
新的可扩展的矩形树布局；改良squarified treemaps；新增binary treemaps。
新增d3.stratify用于处理行列式层次型数据（以前只支持JSON）。
更快，可变的，非递归的四叉树。
泰森多边形暴露有用的拓扑信息。

选择器，过渡，缓动和定时器。

选择器和过渡现在是不变的，提供一个简洁的界面。
新增selection.raise， selection.lower 和selection.dispatch 方法。
时间在后台是冻结的，避免无意识的操作。
定时器可以在外部停止。
过渡现在支持 CSS 变换。
可使用selection.interrupt取消过渡。
更简单的过渡链（d3.active，transition.delay）。
为同质转换提供更好的性能（例如元素间共享插值器）。
更好地执行和持续过渡状态。
修复松紧带缓冲函数和弹性缓冲函数。

其他

默认的轴样式。
更好的刷子交互。
内置的用于并行加载数据的异步队列。
d3.ticks API。

我的感受

2016-5-20日下午五点左右，D3的star数超过50000次，位列所有前端库第二（仅次于boostrap）。自从2013年关注D3以来，几乎都超过每个月1000的增幅上涨着。虽然距离排名第一的前端库boostrap有些差距，但D3的这种发展速度和受欢迎程度相信会继续给我带来更多的惊喜。
翻译D3 V4的API发现与D3 V3的差别很大，功能也更多更完善，就力导向图就从原来的12个功能函数增加到现在的41个（包含二级函数），这势必会给我们做数据可视化带来更多的便利。
路径这部分的API主要用来将Canvas命令转换为SVG路径的d属性的值。本质上最后还是用SVG画图。这一点可能跟我们想要的直接用Canvas画大数据量数据的需求不一样，看来以后还是得手动来实现了，这一点略微还是有些失望的~
D3 V4的大量API由原来的二级函数升级为一级函数（实际上就是把两级的单词合并，使用驼峰命名法重命名了），这样给使用者带来了一些记忆负担，其实以前的API设计得更好用点~

加群讨论

	新手群	专业群	研究群
说明	免费（暂时）	付费	免费（新手别加）
群名	D3.js	D3数据可视化	大数据可视化
群号	437278817	205076374	436442115
二维码

下面是译文，欢迎一起翻译，探讨~

D3: 数据驱动文档（Data-Driven Documents）

D3 (或D3.js) 是一个用来使用Web标准做数据可视化的JavaScript函数库。

D3帮助我们可以融合SVG, Canvas 和 HTML操作技术让数据变得生动有趣。

D3将强大的可视化，动态交互和数据驱动的DOM操作方法完美结合，让我们可以充分发挥现代浏览器的功能，自由地设计正确的可视化界面。

资料

安装

最近的稳定版是 (4.4.0), 可以按照wiki里的安装介绍安装使用。如果你使用NPM, 可执行npm install d3命令。不然的话可以下载最新版。发布包支持AMD, CommonJS, 和 vanilla 环境。自定义编译可以使用 Rollup 或者其他打包工具。也可以直接从d3js.org引用:

<script src="https://d3js.org/d3.v4.min.js"></script>

非压缩版移除上面的.min即可。

API 总览

选择元素

选择 (选择, 修改, 数据, 事件, 控制, 命名空间)

数据类型

数组 (统计, 直方图, 查找, 转换)
集合 (对象, 映射（map）, 集合（set）, 嵌套)
颜色
DSV（分隔符分割的值）
随机值
时间序列

格式化

数字格式化
时间格式化

加载数据

队列
请求

数据映射

比例尺 (连续型, 颜色序数型, 数值型, 序数型, 分类颜色型)

图形几何

形状 (弧, 饼, 线, 面积, 曲线, 符号, 堆叠)
轴
泰森多边形
路径
多边形
四叉树

布局

力布局
层次布局

动态交互

定时器
过渡
插值器
缓动
事件分派
拖动
缩放

D3 使用语义命名。可使用d3.version获取当前版本号。

数组

数组操作，排序，查找，汇总等。

统计

计算基本汇总统计的一些方法。

d3.min - 计算数组中的最小值。
d3.max - 计算数组中的最大值。
d3.extent - 计算数组的范围。
d3.sum - 数组中所有元素求和。
d3.mean - 计算数组的算术平均值。
d3.median - 计算数组的中位数。
d3.quantile - 计算一个数字数组排序后的分位数。
d3.variance - 数组中数字的方差。
d3.deviation - 数组中数字的标准差。

直方图

将离散样本分成连续的无重叠的间隔。

d3.histogram - 创建一个新的直方图生成器。
histogram - 对给定的样本数组计算直方图。
histogram.value - 为每个样本指定一个值访问器。
histogram.domain - 指定可观测值的间隔。
histogram.thresholds - 指定值划分成不同箱的方法。
d3.thresholdFreedmanDiaconis - Freedman–Diaconis装箱规则。
d3.thresholdScott - Scott’s normal reference装箱规则。
d3.thresholdSturges - Sturges’装箱准则。

查找

检索数组中特定的值。

d3.scan - 使用比较器线查找。
d3.bisect - 二分查找排序数组中的值。
d3.bisectRight - 二分查找排序数组中的值。
d3.bisectLeft - 二分查找排序数组中的值。
d3.bisector - 使用访问器和比较器二分查找。
bisector.left - 使用给定的比较器的bisectLeft。
bisector.right - 使用给定的比较器的bisectRight。
d3.ascending - 升序排序。
d3.descending - 降序排序。

转换

转换数组并返回一个新的数组。

d3.merge - 将多个数组合并成一个。
d3.pairs - 创建一个相邻对数组。
d3.permute - 安装指定的索引数组重排数组。
d3.shuffle - 数组随机排序。
d3.ticks - 从一个数组间隔生成有代表的值。
d3.tickStep - 从一个数组间隔生成有代表的值。
d3.range - 生成一组数值。
d3.transpose - 数组转置。
d3.zip - 转置多个数组。

轴

人类可读的刻度轴。

d3.axisTop - 创建一个上部轴生成器。
d3.axisRight - 创建一个右部轴生成器。
d3.axisBottom - 创建一个底部轴生成器。
d3.axisLeft - 创建一个左部轴生成器。
axis - 为给定的选择生成轴。
axis.scale - 设置比例尺。
axis.ticks - 自定义刻度的生成和格式化方式。
axis.tickArguments - 自定义刻度的生成和格式化方式。
axis.tickValues - 明确地指定刻度值。
axis.tickFormat - 明确地指定刻度格式。
axis.tickSize - 设置刻度的大小。
axis.tickSizeInner - 设置内刻度的大小。
axis.tickSizeOuter - 设置外刻度的大小。
axis.tickPadding - 设置刻度和标签之间的间距。

集合

便捷的数据结构，元素的键是字符串类型。

对象

将对象转为数组的方法。

d3.keys - 列举关联数组的键。
d3.values - 列举关联数组的值。
d3.entries - 列举关联数组的键值对实体。

映射

类似ES6 Map，但是键时字符类型的，并且有点其他区别。

d3.map - 创建一个空的map。
map.has - 返回map中是否包含某个值。
map.get - 获取值。
map.set - 设置值。
map.remove - 移除值。
map.clear - 移除所有值。
map.keys - 获取键数组。
map.values - 获取值数组。
map.entries - 获取键值对数组。
map.each - 为每个元素调用一次指定的方法。
map.empty - 返回map是否为空。
map.size - 计算值的数量。

集合

类似ES6 Set，但是键时字符类型的，并且有点其他区别。

d3.set - 创建一个空的set。
set.has - 返回set中是否包含某个值。
set.add - 添加指定值。
set.remove - 删除指定值。
set.clear - 移除所有值。
set.values - 获取值数组。
set.each - 为每个元素调用一次指定的方法。
set.empty - 返回set是否为空。
set.size - 计算值的数量。

嵌套

将数据组织成任意层次。

d3.nest - 创建一个嵌套生成器。
nest.key - 在嵌套层级中加一级。
nest.sortKeys - 当前层级按键排序。
nest.sortValues - 叶子层级按值排序。
nest.rollup -为叶子层指定汇总函数。
nest.map - 生成一个嵌套，返回一个map。
nest.object - 生成一个嵌套，返回一个关联数组。
nest.entries - 生成一个嵌套，返回一个键值对数组。

颜色

颜色操作和颜空间转换。

d3.color - 解析给定的CSS颜色名。
color.rgb - 计算该颜色的RGB值。
color.brighter - 该颜色的高亮副本。
color.darker - 该颜色的较亮副本。
color.displayable - 如果该颜色在标准硬件上可以显示则返回true。
color.toString - 将该颜色格式化为一个十六进制 RGB值字符串。
d3.rgb - 创建一个RGB颜色。
d3.hsl - 创建一个HSL颜色。
d3.lab - 创建一个Lab颜色。
d3.hcl - 创建一个HCL颜色。
d3.cubehelix - 创建一个Cubehelix颜色。

分隔符分隔的值

解析和格式分隔符分隔的值（特别是TSV和CSV）

d3.dsvFormat - 为指定的分隔符指定一个解析器和格式化器。
dsv.parse - 解析给定的字符串返回一组对象。
dsv.parseRows - 解析给定的字符串返回行数组。
dsv.format - 格式化一组对象。
dsv.formatRows - 格式化行数组。
d3.csvParse - 解析给定的CSV字符串，返回一组对象。
d3.csvParseRows - 解析给定的CSV字符串，返回行数组。
d3.csvFormat - 格式化给定的CSV对象。
d3.csvFormatRows - 格式化给定的CSV行数组。
d3.tsvParse -解析给定的TSV字符串，返回一组对象。
d3.tsvParseRows - 解析给定的TSV字符串，返回行数组。
d3.tsvFormat - 格式化给定的TSV对象。
d3.tsvFormatRows - 格式化给定的TSV行数组。

事件分发

命名回调函数。

d3.dispatch - 创建一个定制的事件分发器。
dispatch.on - 注册或者解除注册事件监听器。
dispatch.copy - 创建分发器副本。
dispatch.call - 给注册的监听器分发事件。
dispatch.apply - 给注册的监听器分发事件。

拖曳

使用鼠标或触屏拖曳SVG，HTML 或 Canvas。

d3.drag - 创建一个拖曳行为。
drag - 对一个选择应用拖曳行为。
drag.container - 设置坐标系统。
drag.filter - 忽略一些初始的事件。
drag.subject - 设置被拖曳对象。
drag.x - 设置被拖曳对象的x-坐标。
drag.y - 设置被拖曳对象的y-坐标。
drag.on - 监听拖曳事件。
event.on - 监听当前动作的拖曳事件。

缓动

用来平滑过渡的缓动函数。

ease - 缓动给定的标准化时间。
d3.easeLinear - 线性缓动，就是个恒等函数。

* [d3.easePolyIn](https://github.com/d3/d3-ease#easePolyIn) - 多项式缓动，加速到指定的速率。

* [d3.easePolyOut](https://github.com/d3/d3-ease#easePolyOut) - 逆多项式缓动，等价于1 - polyIn(1 - t)。

* [d3.easePolyInOut](https://github.com/d3/d3-ease#easePolyInOut) - 对称多项式缓动。

* [*poly*.exponent](https://github.com/d3/d3-ease#poly_exponent) - 指定缓动多项式的指数。 ```js var linear = d3.easePoly.exponent(1), quad = d3.easePoly.exponent(2), cubic = d3.easePoly.exponent(3); ``` * [d3.easeQuad](https://github.com/d3/d3-ease#easeQuad) - easeQuadInOut的别名。 * [d3.easeQuadInOut](https://github.com/d3/d3-ease#easeQuadInOut) - 对称平方缓动。