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的源码也有相当大的调整，最明显的是分成了很多小模块单独开发。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）。
新增d3.interpolateDate
d3.interpolate支持特殊的日期
d3.interpolate支持类似数字的对象

形状和布局。

形状支持渲染成Canvas。
增加了参数化的 Catmull–Rom 和natural样条曲线。
新的确定，可扩展的速度Verlet力布局。
新的圆形填充布局。
新的可扩展的矩形树布局；改良squarified treemaps；新增binary treemaps。
新增d3.stratify用于处理行列式层次型数据（以前只支持JSON）。
新增diagram.find支持Voronoi快速检索
添加node.count
包含d3-chord
默认的轴样式。

更快，可变的，非递归的四叉树。
泰森多边形暴露有用的拓扑信息。
使圆形弧线更健壮

修复了cardinal 和 monotone样条曲线。
修复d3.curveCatmullRom中的bug
修复当范围的最小值是非0值时voronoi.size的异常。
修复在voronoi diagram.find时发生崩溃
修复在voronoi diagram.triangles时发生崩溃

修复treemaps中有0值时挂起
修复d3.pack和d3.packSiblings的重叠点bug
修复force.initialize支持孤立点

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

新增selection.raise， selection.lower 和selection.dispatch 方法。
时间在后台是冻结的，避免无意识的操作。
定时器可以在外部停止。
过渡现在支持 CSS 变换。
可使用selection.interrupt取消过渡。

更简单的过渡链（d3.active，transition.delay）。
为同质转换提供更好的性能（例如元素间共享插值器）。
更好地执行和持续过渡状态。

修复松紧带缓冲函数和弹性缓冲函数。
修复链式过渡不会打断它之前的过渡。
修复最后一个节拍抛出错误时过渡不会卡住
修复抛出错误时过渡不会内存泄漏
修复当序数轴过渡被打断时的无效转换

地理

添加projection.fitExtent和projection.fitSize
添加d3.geoIdentity用于缩放，平移和剪切平面几何。
添加d3.geoGraticule10用于生成默认为10°的经纬网
添加d3.geoPath的优化参数用于支持投影和context。
为d3.geoIdentity添加identity.reflectX和identity.reflectY函数
添加path.measure
添加d3.geoContains
d3.geoIdentity的clipExtent替代d3.geoClipExtent
导出原始地理投影。

优化地图投影的默认值
优化d3.geoPath
提高d3.path的性能
优化d3.geoCentroid

修复d3.geoBounds时发生崩溃
修复d3.geoStereographic反转函数
修复d3.geoAlbersUsa缓存失效
修复调用collide.radius没有反应。
修复d3.geoConicConformal反转函数
修复d3.geoConicEqualArea
修复d3.geoPath的默认投影和上下文为null而不是undefined
修复d3.geoBounds计算线几何体的bug
修复d3.geoCentroid计算细节地理特征的bug

数据

添加d3.ticks。
添加d3.cross
d3.pairs添加一个reducer入参
本地数字格式现在可以定义数字系统（如阿拉伯）
内置的用于并行加载数据的异步队列。

修复颜色规范中对不寻常的数字格式的解析
修复interval.every(…).range入参是无效日期时挂起。
修复负无穷的数字格式化
修复d3.interpolateRgb.gamma的透明度插值
time.ticks的step参数改为interval.every。
如果d3.request回调是无效的时候抛出一个异常。
修复d3.queue的await回调函数中吃掉异常

交互

更好的刷子交互。
添加zoom.interpolate来控制聚焦过渡行为
可禁用双击聚焦过渡

修复变焦同时应用到一个元素和其祖先时发生崩溃。
修复在brush.move中清除brush时发生崩溃
修复zoom.translateExtent小于zoom.extent时挂起
修复多点触摸触发的聚焦行为挂起

我的感受

2016-5-20日下午五点左右，D3的star数超过50000次，位列所有前端库第二（仅次于boostrap）。自从2013年关注D3以来，几乎都超过每个月1000的增幅上涨着。严谨的可视化理论、便捷的数据驱动方法和丰富友好的文档案例让社区日渐繁荣。
翻译D3 V4的API发现与D3 V3的差别很大。暴露了更丰富的功能细节，就力导向图就从原来的12个功能函数增加到现在的41个（包含二级函数）。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.7.1), 可以按照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 - 计算一个数字数组排序后的分位数。R和Excel使用的R-7分位数计算法
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.tickIncrement - 增量（ticks中用到）。
d3.range - 生成一组数值。
d3.transpose - 数组转置。
d3.zip - 转置多个数组。
d3.cross - 两个数组的笛卡尔积。

轴

人类可读的刻度轴。

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) - 对称平方缓动。