visx/grid 网格线组件完全指南为 visx 图表添加横向、纵向与极坐标网格【免费下载链接】visx visx | visualization components项目地址: https://gitcode.com/gh_mirrors/vi/visxvisx/grid是 visx 可视化组件库中专用于绘制图表网格线的包GridRows /渲染水平网格线、GridColumns /渲染垂直网格线而Grid /可一次同时渲染两者。本文以 packages/visx-grid/Readme.md 为主线结合仓库源码types.ts、GridRows.tsx、GridColumns.tsx、Grid.tsx 等深入讲解全部组件的属性、默认值与实现原理读完你可以直接在 visx 折线图、柱状图、散点图中快速接入横纵网格也可以在雷达图/玫瑰图中使用极坐标网格GridAngle、GridRadial、GridPolar。包定位与核心组件visx/grid的职责非常单一——根据已有的 scale比例尺在指定宽度/高度范围内生成网格线。它自身不包含坐标轴只负责网格背景。从 src/index.ts 可以确认该包对外导出的全部组件GridRows—— 水平网格线横线GridColumns—— 垂直网格线竖线Grid—— 横线 竖线的组合容器GridAngle—— 极坐标角度网格线从圆心向外辐射的射线GridRadial—— 极坐标径向网格线同心圆弧GridPolar—— 极坐标网格的组合容器角度线 径向线其中前三者服务于常见的直角坐标系图表折线、柱状、散点、面积等后三者服务于极坐标系图表雷达图、玫瑰图等。安装在 React 18 或 19 项目中安装npm install --save visx/grid根据 package.json该包以 React 18/19 为 peerDependencies运行时依赖visx/curve、visx/group、visx/point、visx/scale、visx/shape与classnames这些依赖会在安装时自动带入。包同时提供 CommonJSlib/与 ES Moduleesm/两种产物且声明sideEffects: false可安全参与 tree-shaking。基本用法Grid 组合横纵网格线Readme 中的核心示例展示了最常用的方式——用一个Grid /同时获得横纵两组网格线import { Grid } from visx/grid; // 或者 // import * as Grid from visx/grid; // Grid.Grid / const grid ( Grid xScale{xScale} yScale{yScale} width{xMax} height{yMax} numTicksRows{numTicksForHeight(height)} numTicksColumns{numTicksForWidth(width)} / );要点说明xScale/yScale分别是映射 x、y 坐标的 scale可以是visx/scale创建的 scale也可以是原生 d3-scale见 Grid.tsx 的类型定义GridScale。width/height决定网格线的绘制范围横向线从左边界画到width纵向线从上边界画到height。numTicksRows/numTicksColumns控制横、纵网格线的“近似”条数。注意源码注释特别强调由于 d3 的 tick 算法这个数值是近似的约等于需要精确控制时应改用tickValues。上述示例中numTicksForHeight/numTicksForWidth是 visx 常用的辅助约定即让网格线数量随绘图区域尺寸自适应例如Math.floor(height / 100)Readme 以占位函数形式给出实践中可自行实现或用固定数字。为什么 numTicks 是“近似值”看 GridRows.tsx 的实现const ticks tickValues ?? getTicks(scale, numTicks);。当不传tickValues时网格线位置由visx/scale的getTicks依据 d3 的scale.ticks(count)算法生成。d3 的 tick 算法会根据 scale 的 domain 自动把请求的 tick 数“圆整”到美观的数值如 1、2、5 的倍数因此实际条数可能与传入值略有出入。若你的场景如网格线与坐标轴标签严格对齐要求完全一致请直接传入tickValues。GridRows 与 GridColumns单独使用当只需要一组方向的网格线时可以单独使用GridRows /或GridColumns /。二者实现几乎对称区别仅在于GridRows接收scaley 方向 scale与width横向绘制每条线的 y 坐标由scale(d)计算x 从 0 到width。GridColumns接收scalex 方向 scale与height纵向绘制每条线的 x 坐标由scale(d)计算y 从 0 到height。两个组件的默认值见各自源码的组件签名完全一致top 0、left 0、stroke #eaf0f6浅蓝灰、strokeWidth 1、numTicks 10。import { GridRows, GridColumns } from visx/grid; // 只画横向网格线 GridRows scale{yScale} width{xMax} numTicks{5} stroke#eee / // 只画纵向网格线 GridColumns scale{xScale} height{yMax} numTicks{5} /内部实现从 tick 到 SVG Line以 GridRows.tsx 为例渲染流程为ticks tickValues ?? getTicks(scale, numTicks)得到刻度值数组计算偏移scaleOffset (offset ?? 0) getScaleBandwidth(scale) / 2对每个 ticky coerceNumber(scale(d)) ?? 0 scaleOffset构建from/to两个Point来自visx/point横跨[0, width]用visx/shape的Line /逐条渲染外层包裹visx/group的Group classNamevisx-rows /。值得注意的两点实现细节band 类 scale 的自动居中getScaleBandwidth见 utils/getScaleBandwidth.ts检测 scale 是否具有bandwidth()方法如scaleBand有则取带宽的一半作为偏移让网格线落在 band 的中间而不是边缘。这样在使用scaleBand做柱状图时网格线会与柱子中心对齐。scale 输出非数字的容错coerceNumber保证即使 scale 输出undefined某些 scale 在 domain 外会返回 undefined也回退为 0避免渲染崩溃。类型层面由GridScaleOutput number | NumberLike | undefined见 types.ts承接。通用属性CommonGridProps速查GridRows、GridColumns及极坐标组件共同继承CommonGridProps定义于 types.ts属性类型默认值说明classNamestring—应用到线组g元素的类名children({ lines }) ReactNode—自定义渲染函数接收{ lines: GridLines }覆盖默认的Line渲染top/leftnumber0对网格组容器g的整体平移偏移像素strokestring#eaf0f6网格线描边颜色strokeWidthstring \| number1网格线描边粗细strokeDasharraystring—网格线虚线样式如4,4numTicksnumber10网格线近似条数d3 算法会圆整见上文lineStyleCSSProperties—应用到每条网格线的 style 样式对象offsetnumber—每条网格线的像素平移量Rows 平移 y、Columns 平移 x叠加在 band 居中偏移之上children渲染函数的lines数据结构为GridLines见 types.ts数组元素包含from: { x?, y? }、to: { x?, y? }与index你可以完全自定义网格线的渲染方式例如换成circle或其他标记。此外GridRowsProps/GridColumnsProps还接受tickValues?: ScaleInputScale[]——传入精确刻度值数组指定后覆盖numTicks。同时由于类型定义中AllGridRowsProps/AllGridColumnsProps继承了visx/shape的LineProps与SVGLineElement的原生属性见 GridRows.tsx你还可以直接透传vectorEffect、opacity等任意 SVG 属性到每条线上。Grid 组合组件的专属属性Grid /内部正是把GridRows用yScale与GridColumns用xScale组合进同一个Group classNamevisx-grid见 Grid.tsx。除继承通用属性外它提供成对的前缀属性让横、纵两组网格线可以独立定制属性说明xScale/yScale必填分别映射 xColumns与 yRows坐标xOffset/yOffset对 Columns 线做 x 平移 / 对 Rows 线做 y 平移numTicksRows/numTicksColumns横、纵网格线近似条数rowLineStyle/columnLineStyle分别应用到 Rows / Columns 的 style 对象rowTickValues/columnTickValues横、纵网格线的精确刻度值数组优先于 numTicks*Grid还透传className、stroke、strokeWidth、strokeDasharray等公共属性给两组线restProps也会一并透传给内部的 Rows 与 Columns因此适合把vectorEffectnon-scaling-stroke这类 SVG 属性一次性应用到全部网格线。典型用法让横纵网格线拥有不同样式Grid xScale{xScale} yScale{yScale} width{width} height{height} stroke#ddd strokeWidth{1} numTicksRows{8} numTicksColumns{12} rowLineStyle{{ strokeDasharray: 4,4 }} columnLineStyle{{ strokeDasharray: 2,2 }} /极坐标网格GridAngle、GridRadial 与 GridPolar除直角坐标网格外visx/grid还提供完整的极坐标网格能力通常用于雷达图、玫瑰图或径向条形图。GridAngle角度线辐射射线GridAngle见 GridAngle.tsx根据角度 scale 从圆心向外绘制射线。除通用属性外还有innerRadius默认0射线起始半径outerRadius必填射线终止半径lineClassName应用到所有角度线的类名。实现上每个 tick 的角度为scale(tick) - Math.PI / 2把 d3 角度 scale 的起始方向对齐到 12 点钟方向再经 utils/polarToCartesian.ts 转换为直角坐标的起点与终点最后用Line /渲染。GridAngle scale{angleScale} innerRadius{0} outerRadius{radius} numTicks{12} stroke#ddd /GridRadial径向线同心圆弧GridRadial见 GridRadial.tsx根据径向 scale 绘制同心圆弧内部使用visx/shape的Arc /渲染。专属属性startAngle默认0/endAngle默认2 * Math.PI圆弧的起止角度弧度arcThickness若指定则每条圆弧会具有该厚度用于填充场景此时内半径由scale(radius - arcThickness)计算fill默认transparent/fillOpacity默认1圆弧填充色与不透明度lineClassName应用到所有径向弧线的类名。一个实现细节当不指定arcThickness时内半径取Math.min(...scale.domain())即弧线贴紧 domain 最小值形成常见的“蛛网”式同心圆。GridPolar极坐标组合GridPolar见 GridPolar.tsx是GridAngleGridRadial的组合容器专门为极坐标成对属性例如scaleAngle/scaleRadial、innerRadius/outerRadius、numTicksAngle/numTicksRadial、tickValuesAngle/tickValuesRadial、strokeAngle/strokeRadial、strokeWidthAngle/strokeWidthRadial、strokeDasharrayAngle/strokeDasharrayRadial、lineStyleAngle/lineStyleRadial、classNameAngle/classNameRadial、lineClassNameAngle/lineClassNameRadial、fillRadial、arcThickness、startAngle/endAngle等几乎为每个内部组件属性都提供了带Angle/Radial后缀的独立版本便于分别定制射线与圆弧。GridPolar scaleAngle{angleScale} scaleRadial{radialScale} innerRadius{0} outerRadius{radius} numTicksAngle{12} numTicksRadial{5} strokeAngle#bbb strokeRadial#ddd /测试覆盖与进一步探索该包在 test/ 目录下为每个组件都配备了单元测试Grid.test.tsx、GridRows.test.tsx、GridColumns.test.tsx、GridAngle.test.tsx、GridRadial.test.tsx、GridPolar.test.tsx以及utils.test.ts可在packages/visx-grid目录下通过 vitest 运行。阅读这些测试是理解各组件边界行为如默认值、tickValues优先级、children 自定义渲染的捷径。若想看到网格线的实际应用可参考同仓库的visx/xychartpackages/visx-xychart与visx/chartpackages/visx-chart等更上层封装它们内部即基于此类基础网格组件构建。visx 的网格组件与 packages/visx-axis 的坐标轴组件配合使用即可快速搭建出带完整坐标参考系的专业图表。【免费下载链接】visx visx | visualization components项目地址: https://gitcode.com/gh_mirrors/vi/visx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考