D3.js API 入门

看完该API后，至少会画出一个简单的图形 D3.js 入门

1. d3-selection: 【 选择作图区域 / 添加图形 】
允许强大的数据驱动文档对象模型 (DOM): 设置attributes, styles，properties HTML 或 text 内容等等。使用 data join 的 enter 和 exit 选择集可以用来根据具体的数据 add 或 remove 元素。

常用API

• d3.select( selector ) 从文档中选取第一个元素 ， 返回一个selection
• d3.selectAll( selector ) 从文档中选取所有匹配元素， 返回一个selection
• d3.selector( selector ) 返回一个函数 this 指向匹配到的元素
• d3.selectorAll( selector ) 返回一个函数 this 指向匹配到的元素
• d3.matcher( selector ) 测试一个元素是否符合某种选择器.
• d3.style( node, name ) 返回指定 node 的 name 对应的 style 属性值.

如果 ‘参数’ 为函数，则会在选择前执行对应的函数，并且会传递当前元素的关联数据 (d)，当前的索引 (i) 以及当前分组 (nodes)，在函数中 this 指向当前 DOM 元素(nodes[i]). 为函数时必须return一个元素，或者 null。

选择集可继续进行链式操作

• selection.select( selector )
• selection.selectAll( selector )
• selection.filter( filter ) // filter 可以是一个选择字符串也可以是一个函数
• selection.merge( otherSelection )
  当前选择集中的任何空缺 (null) 都会被指定的 other 中的对应的元素填充(如果存在的话)，
  如果 other 选择集有附加的组或者父元素，则将其忽略。
  如果原选择集与指定的 other 选择集在同样的索引下都有元素，
  则原选择集中的元素会被返回而 other 选择集中的元素会被忽略。
• selection.attr(name[, value]) 设置属性，value 可为函数
• selection.classed(names[, value])
  names 可为数组 指定类名
  value 可为 boolean类型，是否启用names，
  为function时，为每个元素指定， 返回boolean
  为空时，返回selection中第一个非空元素是否启用该names
• selection.style(name[, value[, priority]]) // priority为优先级 null / important
• selection.property(name[, value])
  有些 HTML 元素的属性比较特殊，不能直接使用 attr 和 style 操作，
  比如文本域的 value 属性以及 checkbox 的 checked 属性。使用本方法可以操作这些属性。
• selection.text/html([value])
• selection.append(type)
• selection.insert(type[, before])
  如果 type 为字符串则为选择集中每个选中的插入一个指定类型(标签名)的元素，插入的位置为第一个匹配 before 选择条件的元素
• selection.remove()
  从当前文档中移除选中的元素。返回的选择集(被移除的元素)已经与文档脱离
• selection.clone([deep]) // boolean
• selection.sort(function)
  划重点: 数据绑定和事件
• selection.data([data[, key]])
  当数据分配给元素时，会被存储在元素的 _ data _ 属性上, 因此可以在重新选中元素时继续使用与元素对应的数据。
• selection.enter()
  选择集通常在数据比节点多时用来创建缺失的节点

var div = d3.select("body")
  .selectAll("div")
  .data([4, 8, 15, 16, 23, 42])
  .enter().append("div")
    .text(function(d) { return d; });
// 如果 body 初始为空，
// 则上述代码会创建 6 个新的 DIV 元素并依次添加到 body 中，
// 并且将其文本内容设置为对应的数值

• selection.exit()
  选择集通常用来移除多余的元素

• selection.datum([value]) 单纯的改数据
  获取或设置每个选中元素上绑定的数据。与 selection.data不同, 这个方法不会进行数据链接计算并且不影响索引, 不影响 enter 和 exit 选择集.

• selection.on( typenames[, listener[, capture]] )
  typenames 可多个 'click mouseover ...'
  typenames后面可以跟一个由( . )分割的可选的 name可选的名称允许在同一个事件类型上注册多个回调. 'click.foo'

• 

  其他事件

对selection的控制

• selection.each(function)
• selection.call(function[, arguments…])
• selection.empty() // 当且仅当当前选择集中没有任何元素时返回 true.
• selection.nodes() // 返回选择集中被选中元素的元素数组。
• selection.node() // 返回选择集中第一个非空元素。如果选择集为空则返回 null。
• selection.size() // 返回选择集中包含的元素个数。

---

2. d3-scale: 比例尺 【 计算x，y轴 】
continuous scale： linear, power, log, identity, time, sequential color

• continuous(value) 根据给定的位于 domain 中的 value 返回对应的位于 range 中的值
• continuous.invert(value)

var x = d3.scaleLinear()
    .domain([10, 130])
    .range([0, 960]);

x(20); // 80
x(50); // 320
x.invert(80); // 20
x.invert(320); // 50

• continuous.domain([domain]) 指定多个值的话会生成一个分段的比例尺
• continuous.range([range]) 指定多个值的话会生成一个分段的比例尺

domain 和 range 长度不一致时，取交集

• continuous.clamp( boolean )
  设置钳位，启用后 则能保证返回的值总是处于范围内。

• continuous.ticks([count])

• continuous.tickFormat([count[, specifier]])

var x = d3.scaleLinear()
    .domain([-1, 1])
    .range([0, 960]);

var ticks = x.ticks(5),
    tickFormat = x.tickFormat(5, "+%");

ticks.map(tickFormat); // ["-100%", "-50%", "+0%", "+50%", "+100%"]

• continuous.nice([count])
  比如计算后的 domain 为 [0.201479…, 0.996679…] 时，在经过取整之后会被扩展为 [0.2, 1.0] 取整 仅影响第一个和最后一个值

Scales

• d3.scaleLinear() // 线性比例尺 y = mx + b
• d3.scalePow() // 指数比例尺 y = mx^k + b
  pow.exponent([exponent]) 特殊的方法，获得指数
• d3.scaleLog() // 对数比例尺 y = m log(x) + b.
• d3.scaleSqrt() 开方比例尺
• ... (d3.scaleIdentity(), d3.scaleLog())
• d3.scaleTime() // 需要注意时间类型
  默认的 domain : [2000-01-01, 2000-01-02], range[0, 1]构造一个新的时间比例尺。
  time.ticks([count]) // 间隔数
  time.ticks([interval]) // 间隔时间

var x = d3.scaleTime()
    .domain([new Date(2000, 0, 1, 0), new Date(2000, 0, 1, 2)]);

x.ticks(d3.timeMinute.every(15));
// [Sat Jan 01 2000 00:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:15:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:30:00 GMT-0800 (PST),
//  Sat Jan 01 2000 00:45:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:00:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:15:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:30:00 GMT-0800 (PST),
//  Sat Jan 01 2000 01:45:00 GMT-0800 (PST),
//  Sat Jan 01 2000 02:00:00 GMT-0800 (PST)]

time.tickFormat([count[, specifier]])
time.tickFormat([interval[, specifier]])

%Y - 年份，比如 2011.
%B - 月份，比如 February.
%b %d - 周, 比如 Feb 06.
%a %d - 天, 比如 Mon 07.
%I %p - 时, 比如 01 AM.
%I:%M - 分钟, 比如 01:23.
:%S - 秒, 比如 :45.
.%L - 毫秒, 比如 .012.
//如果想自定义自己的时间格式，请参考 [d3-time-format]

• d3.scaleUtc()
• d3.scaleSequential(interpolator) // 序列比例尺 domain 仅两个数值
  使用跟定的 interpolator 函数构造一个新的序列比例尺。在应用比例尺时，可以传入的值 [0, 1]。其中 0 表示最小值，1表示最大值。例如实现一个 HSL 具有周期性的颜色插值器：

var rainbow = d3.scaleSequential(function(t) {
  return d3.hsl(t * 360, 1, 0.5) + "";
});

• d3.scaleDiverging(interpolator) // 发散比例尺 domain 仅三个数值
• d3.scaleQuantize() // 量化比例尺 【连续输入 => 非连续输出 】 y = m round(x) + b

var width = d3.scaleQuantize()
    .domain([10, 100])
    .range([1, 2, 4]);

width(20); // 1
width(50); // 2
width(80); // 4
width.invertExtent(2); // [40, 70]

• d3.scaleQuantile() // 分位数比例尺 【非连续输入 => 非连续输出 】
  quantile(value)
  quantile.invertExtent(value)
  quantile.quantiles()
• d3.scaleThreshold()

var color = d3.scaleThreshold()
    .domain([0, 1])
    .range(["red", "white", "green"]);

color(-1);   // "red"
color(0);    // "white"
color(0.5);  // "white"
color(1);    // "green"
color(1000); // "green"
color.invertExtent("red"); // [undefined, 0]
color.invertExtent("white"); // [0, 1]
color.invertExtent("green"); // [1, undefined]

• d3.scaleOrdinal([range]) // 序数比例尺
  序数比例尺的输出域和输入域都是离散的。例如序数比例尺可以将一组命名类别映射到一组颜色。或者确定一组条形图在水平方向的位置等等。
  ordinal.unknown([value])
  如果指定了 value 则将未知输入的输出值设置为指定的值。如果没有指定 value 则返回当前的未知值

• d3.scaleBand() // 分段比例尺
  使用空的 domain：[0, 1]，不设置 padding, 不设置 rounding 以及 alignment 构造一个新的分段比例尺。

• d3.scalePoint() // 标点比例尺
  使用空的 domain, 单位 range：[0, 1], 不指定 padding ，rounding 以及 alignment 构造一个新的标点比例尺.

---

3. d3-axis: 坐标轴 【 根据计算的x，y轴创建坐标轴 】
坐标轴组件可以将 scales 显示为人类友好的刻度标尺参考，减轻了在可视化中的视觉任务。

• d3.axisTop(scale)
• d3.axisBottom(scale)
• d3.axisLeft(scale)
• d3.axisRight(scale)

以下 axis = d3.axisRight/..()

• axis.ticks(arguments…)
• axis.ticks([count[, specifier]])
• axis.ticks([interval[, specifier]])
  针对不同比例尺，有不同的ticks

g.append("g").call(d3.axisLeft(y).ticks(10, 'ms'))   // 通过这样的方式 可使用链式调用

• axis.tickValues([values]) // 如果存在value 则更改传入的刻度
• axis.tickFormat([format]) // 更改文本格式化
  控制内侧外侧刻度的大小， 默认为6
• axis.tickSize([size])
• axis.tickSizeInner([size])
• axis.tickSizeOuter([size])
  外侧刻度大小控制着刻度线的长度。外侧刻度表示的是坐标轴最外侧两端的刻度线。内侧刻度和外侧刻度不同，内侧刻度是一个个单独的 line 元素，而外侧刻度则实际上是坐标轴线 path 的一部分。此外外侧刻度可能和第一个或最后一个内侧刻度重合。
• axis.tickPadding([padding]) // 设置刻度和刻度文本之间的间距 默认为3

---