- 核心(Core) - 包括选择器,过渡,数据处理,本地化,颜色等。
- 比例尺(Scales) - 数据编码和视觉编码之间的转换。
- 可缩放矢量图形(SVG) - 提供用于创建可伸缩矢量图形的实用工具。
- 时间(Time) - 解析或格式化时间,计算日历的时间间隔等。
- 布局(Layouts) - 推导定位元素的辅助数据。
- 地理(Geo) - 球面坐标,经纬度运算。
- 几何(Geometry) - 提供绘制2D几何图形的实用工具。
- 行为(Behaviors) - 可重用交互行为。
核心部分
D3 的核心 API 主要包含一些常用的文档操作和数据处理等方面的函数。
在文档操作方面,D3 的核心函数可以选取 DOM 元素,改变元素的属性、样式和内容。还可以追加、插入和删除元素。通过数据绑定可以创建数据驱动的文档。对元素使用过渡函数可以编写生动的动画效果。
选择
一个选择就是从当前文档中选中的一组元素。D3 使用 CSS3 选择器来选择页面元素。
1. d3.select(selector)
选择第一个与 指定字符串 selector
相匹配的元素。如果没有匹配的元素,则返回一个空的选择对象。
例如,对如下结构的两个表格:
<table>
<tr>
<td>苹果</td>
<td>香蕉</td>
<td>西瓜</td>
</tr>
<tr>
<td>桃子</td>
<td id="test">草莓</td>
<td>菠萝</td>
</tr>
</table>
<table>
<tr>
<td>可乐</td>
<td>牛奶</td>
</tr>
<tr>
<td>绿茶</td>
<td class="test">啤酒</td>
</tr>
</table>
下列选择器的选择结果分别是:
d3.select('td') //选择第一个td标签
d3.select('#test') //选择第一个ID名为"test"的元素
d3.select('.test') //选择第一个类名为"test"的元素
例如,我们把选中的元素的背景色设置为橘黄色,字体颜色设置为白色,设置前后的效果如下图所示。
2. d3.select(node)
选择指定的节点。
例如,对上面的表格,想要在单击 body
区域时设置选中元素的字体颜色变为绿色:
d3.select(document.body) //选择body节点
.on("click",function(){
d3.select(this) //选择当前节点,即body节点
.style("color","green");
});
效果如下图所示:
3. selection.append(name)
在当前选择集的最后追加指定名称的子元素,返回的新选择集包含这个新追加的子元素。每个新元素都继承了元素集已绑定的数据。
这个 name
参数可以被指定为一个常量字符串或一个函数。
例如,使用下面的代码添加一个矩形。
//向body标签追加子元素svg
var svg = d3.select("body").append("svg");
//向svg元素追加有svg命名空间的rect子元素
svg.append("svg:rect");//这里省略.attr设置
4. selection.insert(name[,before])
如果指定了 before
参数,则在选择集中的 before
参数指定的元素前添加 name
参数指定的元素;
如果未指定 before
参数或没有子元素匹配 before
参数,则直接使用 selection.append 的规则追加 name
参数指定的元素。这里,参数 name
和 before
都可以被指定为字符串或函数。
//在svg中追加子元素rect,具体设置请参照源码
svg.insert("rect");
//在svg中的rect子元素前增加circle元素
svg.insert("circle", "rect");
//同上,但是before是一个函数
svg.insert("circle", function (d, i) { return "rect"; });
5. selection.remove()
从当前文档删除选择中所有的元素,并将这些元素返回。
//在上例的基础上移除circle元素
var removed=d3.select("circle").remove();
console.log(removed);
6. selection.filter(selector)
过滤选择,返回一个新的选择只包含参数 selector
是 true
的元素。
selector
可以是一个函数或选择字符串。和其他操作符一样,函数有两个参数:d
代表当前元素已绑定的数据,i
代表当前元素在元素集中的索引。
svg.selectAll('text').filter(function(d, i) {
return i % 2 == 0;//i从0开始
}).style("fill", "royalblue");
7. selection.sort(comparator)
用指定的比较函数对当前选择的元素排序,默认为 d3.ascending
(升序排序)。
比较器函数是通过传入两个数据元素(如 a 和 b)进行比较的。若返回值为负,则 a 应该在 b 之前;如果为正,则 a 应该在 b 之后;否则 a 和 b 被认为是相等的。
需要注意的是,这种排序不能保证是稳定的。
但是,可以保证与浏览器内置的数组排序方法具有相同的行为。
例如,按照绑定数据的 value
属性进行升序排序:
svg.selectAll('text').sort(function (a, b) {
return a.value – b.value;
});
8. selection.on(type[,listener[,capture]])
给当前选择的每个元素,绑定或移除指定类型的事件监听器。
type
是一个字符串类型的事件名称,如:“click”、“mouseover” 和 “submit” 等任何支持的 DOM 事件。- 指定的
listener
是一个函数,有两个入参:d
代表当前元素已绑定的数据;i
代表当前元素在元素集中的索引。
- 可选参数
capture
对应于 W3C 的 useCapture 标志,为设定是否为捕获过程,默认事件均为冒泡过程。
例如,单击按钮更改文本内容:
d3.select("button").on("click",function(){
d3.select('svg').selectAll('text')
.text(function (d, i) { return "new:"+d*3; });
});
9. selection.transition()
为当前选择集开启一段过渡动画。过渡的行为和选择类似,只是属性的变化会更平滑地随时间推移,而不是瞬间完成。
例如,为选中的圆元素开启动画,将颜色由橙色过渡为蓝色。
d3.select('svg').append('circle')
.attr({
cx: 100, cy: 100, r: 40,
fill: 'orange'
});
//开启动画,并设置动画结束时填充色为blue
d3.select('svg').select('circle')
.transition()
.attr("fill", "blue");
10. selection.each(function)
为当前选择的每个元素,调用指定的函数。这个函数可以有两个参数:d
代表当前元素已绑定的数据,i
代表当前元素在元素集中的索引。
例如,使用 each
函数为每个圆设置坐标、半径和颜色属性:
//数据集
var dataset=[1,2,3,4,5,6,7,8,9,10];
//颜色比例尺
var color=d3.scale.category20();
//使用数据集添加10个圆
d3.select('svg').selectAll("circle")
.data(dataset)
.enter()
.append('circle');
//使用each函数为每个圆设置属性
d3.selectAll("circle")
.each(function(d){
d3.select(this).attr({
cx: function(d){ return 20*d;},
cy: 100,
r: function(d){ return 3*d;},
fill:color(d)
});
});
11. selection.empty()
如果当前选择为空,则返回 true
。一个选择是空,意味着它不包含任何元素或就是 null 元素。
12. selection.node()
返回当前选择的第一个非空的元素。如果选择为空,则返回 null
。
13. selection.size()
返回在当前选择的元素的总个数。
- d3-scale:https://github.com/d3/d3-scale。比例尺。
- d3-shape:https://github.com/d3/d3-shape。SVG 的 path 非常冗杂,所以 d3-shape 提供了一些让我们非常方便创建并操作 SVG path 的方法。
- d3-hierarchy:https://github.com/d3/d3-hierarchy#d3-hierarchy。层级布局,绘制树状结构的数据。
- d3-zoom:https://github.com/d3/d3-zoom#d3-zoom。缩放。
- d3-force:https://github.com/d3/d3-force#d3-force。力学。