使用 F2 Sunburst 旭日图组件展示层级数据：API 详解与源码原理

数据可视化前端【免费下载链接】F2An elegant, interactive and flexible charting library for mobile.项目地址https://gitcode.com/gh_mirrors/f2/F2点击查看免费下载F2antv/f2是面向移动端的轻量级可视化图形语法库其内置的 Sunburst 旭日图组件用于展示具有层级关系的数据结构每一层圆环代表数据的一个层级扇形的角度与径向宽度共同决定扇区面积从而直观表达数值大小与层级占比。本文以仓库文档 site/docs/api/sunburst.md 为骨架结合 Sunburst 组件源码 与测试用例完整讲解 Sunburst 组件的类型定义、全部 Props 配置、数据格式要求、常见问题排查并深入到 d3-hierarchy 的布局算法与颜色映射实现帮助你在移动端快速落地可交互的旭日图。何时使用旭日图旭日图Sunburst通过同心圆环的径向布局展示层级数据适合以下场景需要展示具有层级结构的数据如分类下的子分类需要通过径向布局直观展示数据比例文件系统目录结构可视化组织架构层级展示预算分配的层级分解市场份额的层级分析与矩形树图Treemap不同旭日图以圆心为中心向外逐层扩展视觉重心更集中尤其适合在移动端小屏幕上展示多层嵌套的分类结构。TypeScript 类型定义Sunburst 组件的完整类型定义位于 withSunburst.tsx与文档中的定义保持一致interface ColorAttrObject { /** 用于颜色映射的字段名 */ field: string; /** 颜色范围数组 */ range?: any[]; /** 自定义颜色映射函数 */ callback?: (value) any; } interface SunburstProps { /** 数据源必须是具有层级结构的数组 */ data: Data; /** 坐标系配置旭日图通常使用极坐标系 polar */ coord?: CoordProps; /** 颜色映射配置可以是颜色数组或包含字段映射的对象 */ color?: any[] | ColorAttrObject; /** 用于确定扇形大小的数值字段名 */ value?: string; /** 是否对数据进行排序默认为 true按数值大小降序排列 */ sort?: boolean | Function; /** 点击事件回调函数 */ onClick?: (event) void; }从源码可见SunburstProps是泛型接口SunburstPropsTRecord extends DataRecorddata要求为 F2 的Data类型。组件通过高阶组件withSunburst(View)生成同时导出SunburstView极坐标环形视图与IcicleView直角坐标冰柱视图供按需使用见 index.tsx。快速上手基础用法在 F2 的 JSX 语法中Sunburst 组件需要作为Canvas的子组件使用data传入嵌套 children 结构的数组import { Canvas, Sunburst } from antv/f2; const data { name: root, children: [ { name: A, children: [ { name: A-1, value: 10 }, { name: A-2, value: 20 }, ], }, { name: B, children: [ { name: B-1, value: 15 }, { name: B-2, value: 25 }, ], }, ], }; const colors [ #5B8FF9, #61DDAA, #65789B, #F6BD16, #7262fd, #78D3F8, #9661BC, #F6903D, #008685, #F08BB4 ]; Canvas context{context} pixelRatio{window.devicePixelRatio} Sunburst data{data.children} coord{{ type: polar }} color{{ field: name, range: colors }} valuevalue / /Canvas其中context为 canvas 的 2d 上下文。仓库中的 站点示例 展示了同样的使用模式先通过document.getElementById(container).getContext(2d)获取 context再构造 JSX 并从props实例化Canvas进行渲染。Props 配置详解基础配置属性类型默认值说明dataArray-数据源必须是具有层级结构的数组children 嵌套valuestring-用于确定扇形大小的数值字段名coordCoordProps{ type: polar }坐标系配置旭日图通常使用极坐标系关于coord源码 view.tsx 中有一个重要的实现细节组件会根据coord.type分流渲染——当coord.type polar时渲染环形扇区视图SunburstView否则渲染矩形冰柱视图IcicleView。也就是说极坐标系是旭日图的默认形态而直角坐标系下会退化为矩形分区布局冰柱图。样式配置属性类型默认值说明colorany[] \| ColorAttrObject主题色颜色映射配置可以是颜色数组或包含字段映射的对象color未配置时默认使用主题色板。主题定义在 theme.ts 中colors: [#1890FF, #2FC25B, #FACC14, #223273, #8543E0, #13C2C2, #3436C7, #F04864],高级配置属性类型默认值说明sortboolean \| Functiontrue是否对数据进行排序默认按 value 降序排列onClick(event) void-点击事件回调函数ColorAttrObject属性类型说明fieldstring用于颜色映射的字段名rangeany[]颜色范围数组callback(value) any自定义颜色映射函数ColorAttrObject内部基于 F2 的分类属性Category实现见 withSunburst.tsx构造时会将Theme.colors作为默认range再与用户传入的color配置合并。用法示例基础旭日图最简单的旭日图配置只声明数据和 value 字段其余全部走默认值const data { name: root, children: [ { name: Category A, children: [ { name: Item 1, value: 10 }, { name: Item 2, value: 20 }, { name: Item 3, value: 15 }, ], }, { name: Category B, children: [ { name: Item 4, value: 25 }, { name: Item 5, value: 30 }, ], }, ], }; Canvas context{context} Sunburst data{data.children} valuevalue / /Canvas自定义颜色直接传入颜色数组组件会按根节点分组依次分配颜色const colors [ #5B8FF9, #61DDAA, #F6BD16, #7262fd, #78D3F8, #9661BC ]; Canvas context{context} Sunburst data{data.children} valuevalue color{colors} / /Canvas使用颜色映射对象通过ColorAttrObject指定字段与颜色范围实现按字段值映射颜色Canvas context{context} Sunburst data{data.children} valuevalue color{{ field: name, range: [#1890ff, #52c41a, #faad14, #f5222d], }} / /Canvas禁用排序设置sort{false}保持数据的原始顺序Canvas context{context} Sunburst data{data.children} valuevalue sort{false} / /Canvas自定义排序函数传入自定义函数控制排序逻辑函数签名与数组的sort回调一致接收两个节点Canvas context{context} Sunburst data{data.children} valuevalue sort{(a, b) { // 按名称排序 return a.name.localeCompare(b.name); }} / /Canvas点击事件通过onClick监听扇区点击Canvas context{context} Sunburst data{data.children} valuevalue onClick{(event) { console.log(点击了扇形:, event); }} / /Canvas从渲染实现看onClick被绑定在每一个节点的group上见 sunburstView.tsx因此点击任意扇区都会触发回调事件对象中带有该节点的相关属性。多层级数据展示 3 层或更多层级的数据children 可以无限嵌套const data { name: root, children: [ { name: Level 1-A, children: [ { name: Level 2-A, children: [ { name: Item 1, value: 5 }, { name: Item 2, value: 10 }, ], }, { name: Level 2-B, children: [ { name: Item 3, value: 8 }, { name: Item 4, value: 12 }, ], }, ], }, ], }; Canvas context{context} Sunburst data{data.children} valuevalue color{{ field: name }} / /Canvas数据格式旭日图要求数据为嵌套的 children 结构const data { name: root, children: [ { name: 第一层级, children: [ { name: 第二层级, children: [ { name: 叶子节点, value: 100 }, ], }, ], }, ], }; // 使用时只传入 children 数组 Sunburst data{data.children} valuevalue /注意事项数据必须是嵌套的 children 结构叶子节点需要包含 value 字段name 字段用于颜色分组仓库的 测试数据 使用经典的 flare 数据集验证了多层级场景其中根节点flare下包含analytics、animate、data、display、flex、physics、query、scale、util、vis十个一级分支每个分支又嵌套 23 层最深可达 4 层是检验多层渲染的典型样例。常见问题旭日图不显示确保数据结构正确且叶子节点包含 value 字段// 错误缺少 value 字段 const data [ { name: A }, { name: B }, ]; // 正确包含 value 字段 const data [ { name: A, value: 10 }, { name: B, value: 20 }, ];层级不正确确保使用嵌套的 children 结构不要使用带 parent 指针的扁平结构// 错误扁平结构 const data [ { name: A, value: 10 }, { name: B, value: 20, parent: A }, ]; // 正确嵌套 children 结构 const data [ { name: A, children: [ { name: B, value: 20 }, ], }, ];颜色不区分确保 color.field 指定的字段在数据中存在// 正确配置颜色映射 Sunburst data{data.children} color{{ field: name }} // name 字段用于分组 valuevalue /排序不生效检查 sort 属性设置// 禁用排序 Sunburst sort{false} / // 自定义排序函数 Sunburst sort{(a, b) a.name.localeCompare(b.name)} /坐标系配置旭日图必须使用极坐标系Sunburst data{data.children} coord{{ type: polar }} // 必须设置为 polar valuevalue /需要说明的是从源码 view.tsx 看若coord.type不为polar组件仍会渲染但会退化为矩形分区的冰柱图IcicleView形态而非环状旭日图要得到文档描述的同心圆环效果必须显式设置coord{{ type: polar }}。源码原理数据如何变成同心圆环理解 Sunburst 的实现有助于排查布局与颜色问题。核心逻辑集中在 withSunburst.tsx 的sunburst()方法中主要分三步第一步构建层级树并求和。使用hierarchy({ children: data }).sum(...)将扁平嵌套数组转换为层级树sum遍历所有节点以value字段作为叶节点数值并向上累加使每个父节点的数值等于其子树之和——这正是扇区面积代表数值比例的数学基础。第二步排序。sort默认为true内置排序函数为(a, b) b[value] - a[value]按 value 降序排列传入函数时使用用户自定义的排序sort{false}时跳过排序。对应源码片段withSunburst.tsxconst root hierarchy({ children: data }).sum(function(d) { return d[value]; }); // 内置按value大小顺序排序支持传入sort函数 if (sort true || isFunction(sort)) { const sortFn isFunction(sort) ? sort : (a, b) b[value] - a[value]; root.sort(sortFn); }第三步分区布局。调用 d3-hierarchy 的partition()布局算法实现位于 partition.js。该算法将整个布局空间按dx/dy归一化根节点占满一个维度其余节点按depth等分另一维度再依据各节点数值比例进行切分treemapDice最终为每个节点计算出x0/x1/y0/y1四个归一化坐标。坐标转换与递归映射。_mapping方法将归一化坐标通过coord.getCoord().convertRect(...)转换到极坐标系下的角度与半径区间x0/x1→ 起始/结束角度y0/y1→ 内径/外径见 sunburstView.tsx最终渲染为sector扇区图形。颜色继承规则。颜色映射的关键函数是rootParentwithSunburst.tsx它向上回溯找到每个节点的第一层根级父节点再以colorAttr.mapping(root.data[colorAttr.field])取色。这就是文档中color.field 指定的字段用于根节点分组所有子节点继承父节点颜色的源码依据——同一顶级分支下的所有子孙扇区共享同一种颜色通过颜色即可快速区分不同的一级分类。注意事项数据结构数据必须是嵌套的 children 结构不能是扁平数组value 字段叶子节点必须包含 value 字段用于确定扇形大小极坐标系coord.type 必须设置为 polar否则会退化为矩形冰柱图布局颜色映射color.field 指定的字段用于根节点分组所有子节点继承父节点颜色排序默认行为sort 默认为 true按 value 值降序排列如需验证组件行为可参考 Sunburst 渲染测试测试以 flare 数据渲染极坐标旭日图并做图像快照比对完整的多层嵌套测试数据见 data.ts可作为构造自己的层级数据的参考模板。赞分享数据可视化前端【免费下载链接】F2An elegant, interactive and flexible charting library for mobile.项目地址https://gitcode.com/gh_mirrors/f2/F2点击查看免费下载相关推荐F2 旭日图Sunburst组件实战指南层级数据径向可视化的配置、原理与场景F2 旭日图Sunburst组件实战指南层级数据径向可视化的配置、原理与场景 旭日图Sunburst是 F2 移动端图表库中用于展示层级数据的径向图表数据可视化前端react-vis 旭日图Sunburst完全指南从数据层次到源码级实现原理react vis 旭日图Sunburst完全指南从数据层次到源码级实现原理 本文基于 react vis 仓库中 docs/sunburst.md ht数据可视化图表库前端Mermaid Live Editor完整使用指南从零绘制到分享图表的免费教程Mermaid Live Editor完整使用指南从零绘制到分享图表的免费教程 Mermaid Live Editor 是 Mermaid 官方出品的免费在线前端开发者工具数据可视化上一篇如何用多智能体AI构建你的专属量化交易策略TradingAgents-CN完整指南下一篇零门槛体验MiMo-7B-RL-ZeroSGLang服务部署与API调用实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考