经过前面的学习，我们已经把渲染引擎和低级可视化模块开发完了，也了解了对应的可视化概念。那么这一章我们就把已经开发好的这些模块串起来，完成“从0到1开发一个图表库”的这一任务。

这一章我们将从 Sparrow 的 API 介绍开始，然后梳理渲染流程，这之后再开始介绍关键代码。这一章可以说是整个实战环节的画龙点睛之笔，那么接下来就让我们开始吧！

# API 设计

首先我们来看看 API 设计，也就是了解一下该如何使用我们最后完成 Sparrow。

Sparrow 最终只暴露出一个函数：plot。该函数根据指定的 options 渲染图表并且返回一个渲染好的 SVG 元素。函数签名可以用 TypeScript 简单地如下定义：

plot(options: SPSpec): SVGSVGElement

@前端进阶之旅: 代码已经复制到剪贴板

至于这个 options 的结构用 TypeScript 可以简单地如下定义：

type SPSpec = SPNode;

type SPNode = {
  type?: string;
  data?: any[],
  scales?: Recode<ChannelTypes, Scale>,
  transforms?: Transform[],
  statistics?: Statistic[],
  encodings?: Recode<ChannelTypes, Encode>,
  guides?: Recode<ChannelTypes, Guide>,
  styles?: Record<string, string>
  children?: SPNode[];
  paddingLeft?: number,
  paddingRight?: number,
  paddingTop?: number,
  paddingBottom?: number,
}

@前端进阶之旅: 代码已经复制到剪贴板

可以发现：它是一个嵌套的结构，描述的是上一章提到的视图树。

每一个节点的 type 除了上一章提到的 layer、col、row 这些容器节点之外，还可以是所有几何元素的类型：interval、area、text 等等，这些被称为视图节点，当然上一章提到的 facet 节点也算是一个视图节点。容器节点可以有 children 属性，但是视图节点不能有 children 属性。

下面对上面的节点的一些属性进行解释：

data：任意类型的数据。
scales：比例尺的配置，比如：{type: 'ordinal', range: ['red', 'yellow']}
transforms：数据预处理配置，比如：data => data.sort()
statistics：统计函数配置，比如：{type: 'stackY'}
encodings：指定几何元素的每个通道用什么编码，比如：{x: 'genre', y: 'sold'}
guides：指定辅助组件的配置，比如：{type: 'axisY', display: false}
styles：指定几何元素的样式，比如：{strokeWidth: 10}
paddingLeft：几何图形区域到整个图表区域的左边距。
paddingRight：几何图形区域到整个图表区域的右边距。
paddingTop：几何图形区域到整个图表区域的上边距。
paddingBottom：几何图形区域到整个图表区域的下边距。

对于容器节点来说，上面的属性对其没有效果，但是会被后代中视图节点继承。比如下面两种写法其实是等价的。

// 可以理解为是下面的语法糖
const options = {
  type: 'layer',
  encodings: {x: 'name', y: 'value'}
  children: [
    {type: 'point'},
    {type: 'line'}
  ],
}

const options = {
  type: 'layer',
  children: [
    // encodings 这个配置继承于父亲
    {type: 'point', encodings: {x: 'name', y: 'value'}},
    {type: 'line', encodings: {x: 'name', y: 'value'}}
  ],
}

@前端进阶之旅: 代码已经复制到剪贴板

有了上面的介绍，接下来来看一个简单的例子。

const sports = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 },
];

@前端进阶之旅: 代码已经复制到剪贴板

如果我们要用 Interval 去可视化上面的数据，那么我们将如下使用 Sparrow：

import { plot } from '@sparrow-vis/plot';

plot({
  type: 'interval', // 指定节点的种类是 interval
  data: sports, // 指定数据
  encodings: {
    x: 'genre', // 指定 x 通道由数据的 genre 属性决定
    y: 'sold', // 指定 y 通道由数据的 sold 属性决定
  },
});

@前端进阶之旅: 代码已经复制到剪贴板

最后的效果如下图：

接下来我们来看一个稍微复杂一点的例子，同样是上面的例子，这次我们来绘制一个饼图。

import { plot } from '@sparrow-vis/plot';

plot({
  type: 'interval',
  data: sports,
  // 将数据的 sold 字段转换成百分比形式
  transforms: [(data) => {
    const sum = data.reduce((total, d) => total + d.sold, 0);
    return data.map(({ genre, sold }) => ({ genre, sold: sold / sum }));
  }],
  // 使用两个坐标系变换：transpose 和 polar
  coordinates: [{ type: 'transpose' }, { type: 'polar' }],
  // 使用一个统计变换 stackY
  statistics: [{ type: 'stackY' }],
  // 设置 x 通道使用的比例尺的 padding 属性
  // interval 的 x 通道必须使用 band 比例尺，所以有 padding 属性
  scales: {
    x: { padding: 0 },
  },
  guides: {
    x: { display: false }, // 不显示 x 方向的坐标轴
    y: { display: false }, // 不显示 y 方向的坐标轴
  },
  encodings: {
    y: 'sold', // y 通道和 sold 属性绑定
    fill: 'genre', // fill 通道和 genre 属性绑定
  },
  // 设置饼图的样式
  styles: {
    stroke: '#000',
    strokeWidth: 2,
  },
})

@前端进阶之旅: 代码已经复制到剪贴板

最后的效果如下：

了解完了 API 设计，接下来就来看看渲染流程，看看 plot 函数是如何将配置转换成 SVG 元素的，或者是如何把数据转换成像素点的。(更多的使用方式可以参看这里的测试代码）。

在开始看代码之前，大家可以先去 Sparrow 的官网看看案例，了解一下 Sparrow 的具体使用方式，然后可以先想想自己会如何去实现。 这之后再读代码的话可以做到事半功倍的效果。

# 渲染流程

Sparrow 整个的渲染流程主要分为下面几个阶段：

预处理：视图节点继承祖先容器节点的属性，同时合并同一区域的属性。
获取通道值：
- 通过 transforms 函数转换数据，获得需要可视化的表格数据。
- 根据编码 encodings 配置从数据中去提取几何图形每个通道对应的值。
- 通过 statsitcs 函数处理获得的通道值，获得最后真正被可视化出来的通道值。
创建比例尺：根据当前的通道值以及 scales 配置去推断对应比例尺种类，定义域和值域的值。
创建辅助组件：根据推断出来的比例尺以及 guides 配置去创建对应的辅助元素。
创建坐标系：根据 coordinates 配置去创建对应的坐标系。
绘制：
- 绘制辅助组件。
- 绘制几何元素。

我们通过上面饼图的例子来展示一下这个流程。最开始的数据如下：

const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 },
];

@前端进阶之旅: 代码已经复制到剪贴板

首先数据会经过如下 transforms 函数的转换，这里面的转换会被合成一个函数。

plot({
  // ...
  transforms: [(data) => {
    const sum = data.reduce((total, d) => total + d.sold, 0);
    return data.map(({ genre, sold }) => ({ genre, sold: sold / sum }));
  }]
  // ...
})

@前端进阶之旅: 代码已经复制到剪贴板

这一步之后的数据如下：

const transformedData = [
  { genre: 'Sports', sold: 0.2722772277227723 },
  { genre: 'Strategy', sold: 0.11386138613861387 },
  { genre: 'Action', sold: 0.1188118811881188 },
  { genre: 'Shooter', sold: 0.3465346534653465 },
  { genre: 'Other', sold: 0.1485148514851485 },
];

@前端进阶之旅: 代码已经复制到剪贴板

数据转换之后将会根据 encodings 去提取数据。

plot({
  // ...
  encodings: {
    y: 'sold', // y 通道和 sold 属性绑定
    fill: 'genre', // fill 通道和 genre 属性绑定
  },
  // ...
})

@前端进阶之旅: 代码已经复制到剪贴板

根据如上的配置会得到如下的结果：

const values = {
  // fill 和 'genre' 字段绑定，所以提取出来是 'genre' 字段的值
  fill: ['Sports', 'Strategy', 'Action', 'Shooter', 'Other'],
  // 没有指定 x 通道的值，默认为 0
  x: [0, 0, 0, 0, 0],
  // 没有指定 x 通道的值，默认为 0
  y1: [0, 0, 0, 0, 0],
  // y 和 'sold' 字段绑定，所以提取出来是 'sold' 字段的值
  y: [0.2722772277227723, 0.11386138613861387, 0.1188118811881188, 0.3465346534653465, 0.1485148514851485]
};

@前端进阶之旅: 代码已经复制到剪贴板

这之后就会就会经过 statistics 去处理数据。

接下来就是根据获得的通道值创建比例尺了。

# API 设计

# 渲染流程

# plot

# 小结

实战 渲染流程 Plot|可视化专题

实战 渲染流程 Plot|可视化专题

实战渲染流程 Plot|可视化专题

实战渲染流程 Plot|可视化专题