F2 旭日图（Sunburst）组件实战指南：层级数据径向可视化的配置、原理与场景-平芜编程栈

数据可视化
前端

【免费下载链接】F2

📱📈An elegant, interactive and flexible charting library for mobile.

项目地址：https://gitcode.com/gh_mirrors/f2/F2

旭日图（Sunburst）是 F2 移动端图表库中用于展示层级数据的径向图表组件，它通过同心圆环的嵌套关系直观呈现数据的层级结构：每一层圆环代表一个层级，扇区的大小（角度或弧长）反映数据数值。本文将围绕 F2 官方案例文档 site/examples/relation/sunburst/index.zh.md 中的核心配置与代码演示，结合组件源码（packages/f2/src/components/sunburst/）与测试用例（packages/f2/test/components/sunburst/index.test.tsx），完整讲解基础用法、Props 参数、底层布局算法与典型使用场景，帮助你快速在移动端项目中落地旭日图。

什么是旭日图

旭日图是一种径向排布的层级数据图表，由中心向外层层扩展的同心圆环组成：

每一层圆环对应数据树中的一个层级（从根节点到各级子节点）；
同一层内，扇区的角度大小与节点数值成正比，角度越大代表该数据项的数值越大；
不同层级之间通过不同半径的圆环区分，层与层之间用分隔线（默认白色细线）隔开，使层级归属一目了然。

它兼具"结构展示"与"数值比较"两种能力，尤其适合在有限屏幕空间（如移动端）内呈现深层次、多分支的树形数据。

基础示例与代码演示

F2 官方示例文档提供了完整可运行的基础旭日图 demo。其核心 JSX 代码如下：

import { jsx, Canvas, Sunburst } from '@antv/f2'; const { props } = ( <Canvas context={context}> <Sunburst data={data.children} coord={{ type: 'polar', }} color={{ field: 'name', }} value="value" space={4} /> </Canvas> ); const chart = new Canvas(props); chart.render();

在完整 demo 中，数据通过fetch异步获取（sunburst.jsx），渲染前先创建 Canvas 上下文，并通过new Canvas(props)与chart.render()完成挂载。注意data传入的是data.children——即从树的"根的子节点"开始，根节点本身不参与绘制。

配置要点速览：

配置项	示例值	作用
`data`	`data.children`	层级数据数组（每项可含`children`子树）
`coord`	`{ type: 'polar' }`	极坐标系，旭日图的径向形态由此产生
`color`	`{ field: 'name' }`	按`name`字段为每个分类分配颜色
`value`	`"value"`	指定决定扇区大小的数值字段
`space`	`4`	扇区之间的间距（单位像素）

组件 Props 详解

根据 SunburstProps 接口定义，Sunburst组件支持以下属性：

属性	类型	默认值	说明
`data`	`Data`	-	层级结构数据数组（必填），子级通过`children`字段嵌套
`coord`	`CoordProps`	-	坐标系配置，旭日图使用`{ type: 'polar' }`极坐标
`color`	`Array \\| ColorAttrObject`	-	颜色映射配置，可为颜色数组或对象
`value`	`string`	-	指定节点数值字段名，用于计算扇区大小
`sort`	`boolean \\| Function`	`true`	是否按数值排序，或传入自定义排序函数
`onClick`	`(ev) => void`	-	扇区点击事件回调

其中ColorAttrObject的结构为：

interface ColorAttrObject { field: string; // 用于颜色映射的字段名 range?: any[]; // 颜色范围数组，不传时使用主题默认色板 callback?: (value) => any; // 自定义颜色映射函数 }

坐标系配置 coord

旭日图形态完全依赖坐标系：coord传{ type: 'polar' }时渲染为径向圆环，传其他类型（如默认的直角坐标系）时则渲染为矩形的"冰柱图（Icicle）"形态。这个分支逻辑在 view.tsx 中体现：

if (coord.type === 'polar') { return <SunburstView {...props} />; } return <IcicleView {...props} />;

也就是说，同一个Sunburst组件配合不同坐标系即可输出两种不同的层级可视化：极坐标下的旭日图与直角坐标下的冰柱图，二者共享同一套数据布局逻辑。

颜色映射 color

color的field指定分类字段后，组件内部会创建一个Category分类颜色属性（withSunburst.tsx）：

this.color = new Category({ range: Theme.colors, // 默认使用主题色板 ...color, data, });

在_mapping阶段，每个节点通过rootParent回溯到最顶层父节点（深度为 1 的层级），再根据该父节点在color.field字段上的值映射颜色（withSunburst.tsx）。这意味着一级分类之下的所有子孙扇区共享同一种颜色，整个子树用同一色相呈现，视觉上更易区分大类归属。

数据格式与准备

旭日图要求嵌套的树形结构数据。每个节点对象至少包含：

{ name: 'analytics', // 分类字段，用于颜色映射 children: [ // 子节点数组（叶子节点可省略） { name: 'cluster', children: [...] }, { name: 'graph', value: 5731 }, ], // 叶子节点需要 value 数值字段 }

value字段（本例为"value"）用于计算扇区大小。测试用例 data.ts 中使用的是一棵经典的多级分类树（如analytics→cluster→AgglomerativeCluster: 3938），叶子节点均带数值，中间节点则通过子节点数值累加得到权重。

数值不一定是叶子专属：中间节点也可以显式携带value，布局算法求和时会叠加计算。整体遵循"父节点权重 = 自身权重 + 子节点权重之和"的规则。

源码级原理：层级布局与渲染

布局算法：hierarchy + partition

Sunburst的布局核心位于 withSunburst.tsx 的sunburst()方法，它复用了仓库内置的 d3-hierarchy 实现，链路如下：

构建层级树：hierarchy({ children: data }).sum(...)将扁平嵌套数组转为层级对象，sum按value字段自底向上累加每个节点的权重；
排序：默认按value从大到小排序，也支持传入自定义排序函数（sort为函数时使用函数，sort = false时跳过排序）；
切分布局：partition()将层级树切分为各层圆环，为每个节点计算x0/x1（角度区间）与y0/y1（半径区间）；
坐标映射：_mapping通过coord.getCoord().convertRect({ x: [x0, x1], y: [y0, y1] })将布局区间转换为极坐标系下的真实像素几何（withSunburst.tsx），得到每个节点的xMin/xMax/yMin/yMax与color。

渲染层：递归绘制扇区

SundburstView（太阳图视图）是极坐标形态的渲染器：以坐标系中心coord.center为圆心，对每个节点递归绘制<sector>扇区，startAngle/endAngle取自角度区间xMin/xMax，内外半径r0/r取自半径区间yMin/yMax，填充色为映射后的color，并以 1px 白色描边区分相邻扇区：

<sector attrs={{ cx: x, cy: y, lineWidth: '1px', stroke: '#fff', startAngle: `${xMin} rad`, endAngle: `${xMax} rad`, r0: yMin, r: yMax, fill: color, }} />

节点若存在子节点，则递归进入下一层绘制（sunburstView.tsx），由此形成"由内向外逐层展开"的圆环结构。

冰柱图渲染

当坐标系不是 polar 时，IcicleView 负责渲染：每个节点绘制一个<rect>矩形，width与height由xMin/xMax、yMin/yMax计算，颜色映射逻辑完全一致。这种形态适合在直角坐标空间中展示层级占比，例如作为旭日图的"扁平化"替代方案。

测试验证

测试用例 index.test.tsx 以{ type: 'polar' }坐标 +field: 'name'颜色映射渲染样例数据，并通过toMatchImageSnapshot()做图像快照对比。测试数据的渲染结果（渲染快照）清晰展示了多层圆环、按大类共享颜色的效果：各一级分类扇区以不同色系铺满对应角度范围，外层细分扇区按子节点数量密度自然分布。

使用场景

官方文档将旭日图的适用场景归纳为四类，均符合"层级 + 数值占比"的数据特征：

文件系统目录结构展示：目录、子目录与文件大小，外环细扇区对应文件，内环粗扇区对应目录；
组织架构的可视化：部门 → 团队 → 成员，扇区面积可映射团队规模或预算；
分类数据的层级展示：商品大类 → 子类 → SKU，观察各分类对总体的贡献；
预算分配和资源分布分析：总预算逐级下钻到具体项目，直观对比各分支的资源占比。

与同目录下的矩形树图（Treemap）文档对比：Treemap 用矩形面积表达数值、适合"空间利用率优先"的扁平层级；旭日图用圆环角度表达数值、适合"强调层级嵌套关系与整体占比"的场景。两者共用嵌套数据模型，可根据业务形态选择。

进阶配置与注意事项

排序策略：sort默认开启且按value降序，让大数值扇区优先占据起始角度；若希望保留数据原有顺序，可设置sort={false}；若需自定义规则（如按字母序），传入函数(a, b) => ...即可（withSunburst.tsx）。
扇区间距：space={4}控制扇区间的留白，数值越大扇区边界越清晰，但过大会压缩有效绘图区域；测试默认配置中该值可省略。
颜色层级：颜色基于一级分类（深度为 1 的根节点）映射，同一子树共享颜色——如果希望叶子节点也独立配色，可自定义color.callback实现细粒度映射。
事件交互：onClick回调会随每个扇区的<group onClick>绑定（sunburstView.tsx），可用于点击下钻或详情展示等移动端交互。
数据校验：务必保证value字段存在于数据中，且叶子节点携带数值；color.field指定的字段需在顶层分类中存在，否则颜色无法正确分组。

总结

F2 的Sunburst组件以"嵌套数据 + 极坐标 + hierarchy/partition 布局"三件套，在移动端画布上高效渲染层级数据的径向视图。通过官方示例的coord、color、value、space四个核心配置即可快速上手；深入源码可看到它与冰柱图共享同一套布局管线，仅因坐标系不同而切换渲染视图。对于文件目录、组织架构、分类占比等"层级 + 数值"型数据，旭日图是兼顾美观与信息密度的首选方案。