尧图网页设计 
Recharts 示例图表开发规范从零编写官网示例与可视化回归测试【免费下载链接】rechartsRedefined chart library built with React and D3项目地址: https://gitcode.com/GitHub_Trending/re/rechartsRecharts 是一个基于 React 与 D3 构建的开源图表库其官方网站www目录下的文档站通过大量示例图表Example向开发者演示各类图表 API 的用法。本文以仓库中的 .agents/skills/example/SKILL.md 为核心指南系统讲解在 Recharts 仓库中编写一个合规、可复用、可测试的示例组件的完整流程从文件结构约束、注入依赖的使用、到CodeEditorWithPreview集成、Controls/Levers 交互面板再到 Playwright 可视化回归VR测试的编写与截图生成。读完本文你将掌握 Recharts 官网示例的标准开发范式并能在本地复现整套示例 交互控制 VR 测试的工作流。什么是 Recharts 示例Example根据 SKILL.md 的定义Recharts 示例本质上是一个JSX 组件它渲染一个图表被用于官网的指南Guides与 API 文档中用来演示 Recharts 某个具体特性的用法。示例的定位是单文件、独立、只面向公共 API一个示例就是一个独立文件本身是完整的、可独立运行的组件每个示例聚焦演示 Recharts 的某一个具体特性如默认索引、动画时长、图例位置等不得导入 Recharts 的任何内部组件或工具函数只能使用recharts包导出的公共 API示例 中所有图表组件均直接来自import { Area, AreaChart, XAxis, YAxis, ... } from recharts。这一约束保证了示例代码对用户而言所见即所得——示例里出现的 import 语句就是用户在自己项目里也能直接复制的代码。示例文件的注入依赖示例文件虽然不允许导入 Recharts 内部实现但 Recharts 会在示例运行环境中默认注入以下依赖因此这些包的导入是被允许的reactreact-domreact-isrecharts/devtools其中recharts/devtools提供了两个对示例尤其有用的能力同样被 CodeEditorWithPreview 的运行作用域 所支持编辑模式下react-runner会以react、recharts、d3-shape、recharts/devtools作为可解析模块注入generateMockData生成随机图表数据的函数让示例不必硬编码数据。可选但推荐使用。RechartsDevtools用于调试的子组件官方强烈建议每个图表都挂上它。使用 generateMockData 生成稳定数据generateMockData接受数据长度与seed种子两个参数用 seed 而非真正的随机数目的是保证跨渲染、跨环境如 CI 与本地得到一致的数据从而让 VR 测试可以稳定对比截图。仓库中的实际用法可见 SimpleAreaChart.tsxconst data generateMockData(6, 4390435);以及 SKILL.md 中的最小骨架import { generateMockData, RechartsDevtools } from recharts/devtools; import { Area, AreaChart } from recharts; const lengthOfData 10; const seed 123; // 使用 seed 而非真正随机数据保证跨渲染一致可运行 VR 测试 const data generateMockData(lengthOfData, seed); export default function Example() { return ( AreaChart width{400} height{400} data{data} Area dataKeyvalue / RechartsDevtools / {/* ... 更多组件 */} /AreaChart ); }示例的导出约定示例文件必须默认导出一个 React 组件default export。真实示例会比上面的骨架使用更多 Recharts 组件与特性但文件结构与注入依赖的用法保持不变。在指南与 API 文档中使用示例示例创建完成后最常见的用法是作为CodeEditorWithPreview组件的 prop 传入。这个标准化编辑器负责渲染示例、展示源码并附带若干增强能力CodeEditorWithPreview.tsx 是其完整实现。基本用法// 相对路径需根据 guide 所在位置调整 import { CodeEditorWithPreview } from ../../CodeEditorWithPreview.tsx; import PieChartDefaultIndex from ./PieChartDefaultIndex.tsx; import PieChartDefaultIndexSource from ./PieChartDefaultIndex.tsx?raw; // 其余代码省略 ... CodeEditorWithPreview Component{PieChartDefaultIndex} sourceCode{PieChartDefaultIndexSource} stackBlitzTitleRecharts PieChart Default Index Example /;要点说明Component要渲染的示例组件默认导出的那个组件sourceCode示例源码字符串通过 Vite 的?raw后缀以原始文本导入供编辑器展示与Run执行stackBlitzTitle在 StackBlitz 中打开该项目时使用的标题。从 CodeEditorWithPreview 的 Props 类型 可以看到它支持的全部属性除上述三个必填项外还有可选的defaultControlsState、levers、analyticsLabel、defaultTool与defaultToolTab。组件内置的交互工具ToolsCodeEditorWithPreview内置了四个标签页工具见 actualTools 定义Source code源码编辑器CodeMirror默认只读点击Edit按钮后进入编辑模式可修改代码并点击Run通过react-runner实时执行工具栏同时提供Copy与Open in StackBlitz按钮Hook inspector基于recharts/devtools的调试面板可检查图表内部 Hook 状态Annotations注解面板Controls交互控制面板仅在同时提供了defaultControlsState与levers时渲染渲染条件见源码。另外注意组件把示例的交互状态通过useSessionStorageState按${stackBlitzTitle}:levers-v1为 key 持久化到 sessionStorage刷新页面后用户调过的控制项会保留相关代码。Controls / Levers 交互控制可选Controls 是CodeEditorWithPreview的一项能力允许用户动态修改示例组件的 props从而直观演示不同 props 对图表的影响。推荐的实现方式而非导出 Controls 组件官方推荐的做法是不要单独导出一个Controls组件而是导出两个东西defaultControlsState初始的可序列化状态对象levers一个 lever控制杆定义数组。示例组件本身应接收该状态对象作为 props通常是PartialT并在组件内部与默认值合并。典型结构如下摘自 SKILL.mdimport type { Lever } from ../../Shared/levers/Levers.tsx; import { animationDurationLever } from ../../Shared/levers/gallery/animationDurationLever.tsx; import { replayAnimationLever } from ../../Shared/levers/gallery/replayAnimationLever.tsx; type ControlsState { animationDuration: number; replayKey: number; }; export const defaultControlsState: ControlsState { animationDuration: 600, replayKey: 0, }; export const levers [ replayAnimationLeverControlsState(), animationDurationLeverControlsState(), ] satisfies ReadonlyArrayLeverControlsState;然后传给CodeEditorWithPreviewCodeEditorWithPreview Component{MyExample} sourceCode{MyExampleSource} defaultControlsState{defaultControlsState} levers{levers} stackBlitzTitleRecharts example defaultToolcontrols /其中defaultToolcontrols让页面初始就展示控制面板。复用 gallery 中预置的 lever优先使用 www/src/components/Shared/levers/gallery/ 下预置的 gallery lever。当前仓库已包含以下现成控制项Lever 文件类型用途animationBeginLever.tsx范围滑块动画开始延迟animationDurationLever.tsx范围滑块动画时长100–3000ms步长 100animationEasingLever.tsx下拉选择动画缓动函数animationMatchByLever.tsx下拉选择动画匹配策略cartesianLayoutLever.tsx下拉选择直角坐标系布局方向isAnimationActiveLever.tsx开关是否启用动画replayAnimationLever.tsx动作按钮触发动画重放replayKey 1streamWindowLever.tsx滑块/数字流式数据窗口swapDataLever.tsx动作按钮切换数据集themeLever.tsx下拉选择明暗主题切换例如 animationDurationLever.tsx 内部用createRangeLever生成一个 range 输入绑定state.animationDuration并映射回{ ...state, animationDuration }replayAnimationLever.tsx 则用createActionLever生成一个▶ Replay animation按钮点击后replayKey 1。若某个控制项很可能被多个示例复用就应该把它加进 gallery而不是在每个示例文件里临时造一套 UI。自定义 lever 的五种构造器如果 gallery 中没有合适的控制项可以使用 Levers.tsx 提供的构造器自己定义。LeverTState类型要求提供key与一个接收{ state, setState, htmlId }的组件htmlId应绑定到输入元素上以关联labelcreateActionLever按钮型点击触发一次动作如重放动画createRangeLever范围滑块支持min/max/step与可选的formatValue格式化显示值createNumberLever数字输入框同样支持min/max/stepcreateSelectLever下拉选择通过options: ReadonlyArray{ value, label }提供选项选中值必须是字符串createCheckboxLever复选框绑定布尔值。仓库中的真实范例是 LegendPositionExample.tsx它定义了ControlsState { position, layout, offset }用createSelectLever提供 13 种图例位置与 3 种布局选项用createNumberLever提供 0–100 的 offset然后在组件内部通过const { position, layout, offset } { ...defaultControlsState, ...props }合并默认值合并逻辑见该文件。控制状态的硬性要求控制状态必须保持可序列化serializable只存index | append、a | b这类简单键值再把键映射到示例组件内部的运行时函数或数据集Levers 是可选的并非每个示例都需要交互控制。可视化回归测试VR Test官方强烈建议为每个新示例配套编写 VR 测试。所有官网示例的 VR 测试都放在test-vr/tests/www/目录下测试文件命名为YourExampleName.spec-vr.tsx。一个完整的 VR 测试文件如下摘自 SKILL.mdimport * as React from react; import { test, expect } from playwright/experimental-ct-react; import TooltipStylesExample from ../../../www/src/docs/exampleComponents/Tooltip/TooltipStylesExample; test(TooltipStylesExample, async ({ mount }) { const component await mount(TooltipStylesExample /); await expect(component).toHaveScreenshot(); });仓库的 VR 测试基础设施位于 test-vr/ 目录配置见 test-vr/playwright.config.ts测试运行基于playwright/experimental-ct-reactPlaywright Component Testing。编写 VR 测试的关键注意点路径映射测试文件必须使用相对路径指回www/src/...如上面的../../../www/src/docs/exampleComponents/...结构约束Playwright CT 要求组件从独立文件中导入不能在测试文件内联声明组件Props 传递如果示例不接受 props直接ExampleComponent /挂载即可如果示例接受 props如 levers/controls 相关则需要按CodeEditorWithPreview的传参方式原样传入保证测试与真实页面行为一致截图生成生成截图需要 Docker而当前环境可能并未配置 Docker。需要提醒使用者必须在本地生成截图并提交到仓库VR 截图存放于 test-vr/snapshots/tests/该目录已收录 1000 张 PNG 基线截图。与示例的数据稳定性配合VR 测试能稳定工作的前提正是前面提到的generateMockData(length, seed)seed 固定后每次渲染数据一致toHaveScreenshot()才能与仓库中的基线截图逐像素比对。这也解释了为什么 SKILL.md 明确建议示例使用 seed 生成数据。完整开发流程小结结合 SKILL.md 与仓库实现一个示例从创建到上线的完整链路为创建示例文件在 www/src/docs/exampleComponents/ 下新建单文件组件只导入recharts公共 API 与注入依赖用generateMockData(length, seed)生成稳定数据默认导出组件并挂上RechartsDevtools /可选添加交互控制定义defaultControlsState与levers优先复用 gallery lever接入文档在指南或 API 文档如 www/src/components/GuideView/ 下的各指南页面中用CodeEditorWithPreview包裹示例传入Component、sourceCode?raw导入与stackBlitzTitle编写 VR 测试在 test-vr/tests/www/ 下创建YourExampleName.spec-vr.tsx按 Playwright CT 规范挂载示例并断言截图生成并提交基线截图在配置了 Docker 的本地环境运行 Playwright 生成截图将其提交到仓库test-vr/snapshots/tests/使 CI 与本地都能进行稳定的回归比对。通过这条流水线Recharts 官网的每一个示例都同时满足可读源码清晰、可玩Controls 交互、可验VR 回归三个标准而这套范式也可以直接迁移到你自己的 Recharts 图表组件库或文档站点建设中。【免费下载链接】rechartsRedefined chart library built with React and D3项目地址: https://gitcode.com/GitHub_Trending/re/recharts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Recharts 示例图表开发规范：从零编写官网示例与可视化回归测试
Recharts 示例图表开发规范从零编写官网示例与可视化回归测试【免费下载链接】rechartsRedefined chart library built with React and D3项目地址: https://gitcode.com/GitHub_Trending/re/rechartsRecharts 是一个基于 React 与 D3 构建的开源图表库其官方网站www目录下的文档站通过大量示例图表Example向开发者演示各类图表 API 的用法。本文以仓库中的 .agents/skills/example/SKILL.md 为核心指南系统讲解在 Recharts 仓库中编写一个合规、可复用、可测试的示例组件的完整流程从文件结构约束、注入依赖的使用、到CodeEditorWithPreview集成、Controls/Levers 交互面板再到 Playwright 可视化回归VR测试的编写与截图生成。读完本文你将掌握 Recharts 官网示例的标准开发范式并能在本地复现整套示例 交互控制 VR 测试的工作流。什么是 Recharts 示例Example根据 SKILL.md 的定义Recharts 示例本质上是一个JSX 组件它渲染一个图表被用于官网的指南Guides与 API 文档中用来演示 Recharts 某个具体特性的用法。示例的定位是单文件、独立、只面向公共 API一个示例就是一个独立文件本身是完整的、可独立运行的组件每个示例聚焦演示 Recharts 的某一个具体特性如默认索引、动画时长、图例位置等不得导入 Recharts 的任何内部组件或工具函数只能使用recharts包导出的公共 API示例 中所有图表组件均直接来自import { Area, AreaChart, XAxis, YAxis, ... } from recharts。这一约束保证了示例代码对用户而言所见即所得——示例里出现的 import 语句就是用户在自己项目里也能直接复制的代码。示例文件的注入依赖示例文件虽然不允许导入 Recharts 内部实现但 Recharts 会在示例运行环境中默认注入以下依赖因此这些包的导入是被允许的reactreact-domreact-isrecharts/devtools其中recharts/devtools提供了两个对示例尤其有用的能力同样被 CodeEditorWithPreview 的运行作用域 所支持编辑模式下react-runner会以react、recharts、d3-shape、recharts/devtools作为可解析模块注入generateMockData生成随机图表数据的函数让示例不必硬编码数据。可选但推荐使用。RechartsDevtools用于调试的子组件官方强烈建议每个图表都挂上它。使用 generateMockData 生成稳定数据generateMockData接受数据长度与seed种子两个参数用 seed 而非真正的随机数目的是保证跨渲染、跨环境如 CI 与本地得到一致的数据从而让 VR 测试可以稳定对比截图。仓库中的实际用法可见 SimpleAreaChart.tsxconst data generateMockData(6, 4390435);以及 SKILL.md 中的最小骨架import { generateMockData, RechartsDevtools } from recharts/devtools; import { Area, AreaChart } from recharts; const lengthOfData 10; const seed 123; // 使用 seed 而非真正随机数据保证跨渲染一致可运行 VR 测试 const data generateMockData(lengthOfData, seed); export default function Example() { return ( AreaChart width{400} height{400} data{data} Area dataKeyvalue / RechartsDevtools / {/* ... 更多组件 */} /AreaChart ); }示例的导出约定示例文件必须默认导出一个 React 组件default export。真实示例会比上面的骨架使用更多 Recharts 组件与特性但文件结构与注入依赖的用法保持不变。在指南与 API 文档中使用示例示例创建完成后最常见的用法是作为CodeEditorWithPreview组件的 prop 传入。这个标准化编辑器负责渲染示例、展示源码并附带若干增强能力CodeEditorWithPreview.tsx 是其完整实现。基本用法// 相对路径需根据 guide 所在位置调整 import { CodeEditorWithPreview } from ../../CodeEditorWithPreview.tsx; import PieChartDefaultIndex from ./PieChartDefaultIndex.tsx; import PieChartDefaultIndexSource from ./PieChartDefaultIndex.tsx?raw; // 其余代码省略 ... CodeEditorWithPreview Component{PieChartDefaultIndex} sourceCode{PieChartDefaultIndexSource} stackBlitzTitleRecharts PieChart Default Index Example /;要点说明Component要渲染的示例组件默认导出的那个组件sourceCode示例源码字符串通过 Vite 的?raw后缀以原始文本导入供编辑器展示与Run执行stackBlitzTitle在 StackBlitz 中打开该项目时使用的标题。从 CodeEditorWithPreview 的 Props 类型 可以看到它支持的全部属性除上述三个必填项外还有可选的defaultControlsState、levers、analyticsLabel、defaultTool与defaultToolTab。组件内置的交互工具ToolsCodeEditorWithPreview内置了四个标签页工具见 actualTools 定义Source code源码编辑器CodeMirror默认只读点击Edit按钮后进入编辑模式可修改代码并点击Run通过react-runner实时执行工具栏同时提供Copy与Open in StackBlitz按钮Hook inspector基于recharts/devtools的调试面板可检查图表内部 Hook 状态Annotations注解面板Controls交互控制面板仅在同时提供了defaultControlsState与levers时渲染渲染条件见源码。另外注意组件把示例的交互状态通过useSessionStorageState按${stackBlitzTitle}:levers-v1为 key 持久化到 sessionStorage刷新页面后用户调过的控制项会保留相关代码。Controls / Levers 交互控制可选Controls 是CodeEditorWithPreview的一项能力允许用户动态修改示例组件的 props从而直观演示不同 props 对图表的影响。推荐的实现方式而非导出 Controls 组件官方推荐的做法是不要单独导出一个Controls组件而是导出两个东西defaultControlsState初始的可序列化状态对象levers一个 lever控制杆定义数组。示例组件本身应接收该状态对象作为 props通常是PartialT并在组件内部与默认值合并。典型结构如下摘自 SKILL.mdimport type { Lever } from ../../Shared/levers/Levers.tsx; import { animationDurationLever } from ../../Shared/levers/gallery/animationDurationLever.tsx; import { replayAnimationLever } from ../../Shared/levers/gallery/replayAnimationLever.tsx; type ControlsState { animationDuration: number; replayKey: number; }; export const defaultControlsState: ControlsState { animationDuration: 600, replayKey: 0, }; export const levers [ replayAnimationLeverControlsState(), animationDurationLeverControlsState(), ] satisfies ReadonlyArrayLeverControlsState;然后传给CodeEditorWithPreviewCodeEditorWithPreview Component{MyExample} sourceCode{MyExampleSource} defaultControlsState{defaultControlsState} levers{levers} stackBlitzTitleRecharts example defaultToolcontrols /其中defaultToolcontrols让页面初始就展示控制面板。复用 gallery 中预置的 lever优先使用 www/src/components/Shared/levers/gallery/ 下预置的 gallery lever。当前仓库已包含以下现成控制项Lever 文件类型用途animationBeginLever.tsx范围滑块动画开始延迟animationDurationLever.tsx范围滑块动画时长100–3000ms步长 100animationEasingLever.tsx下拉选择动画缓动函数animationMatchByLever.tsx下拉选择动画匹配策略cartesianLayoutLever.tsx下拉选择直角坐标系布局方向isAnimationActiveLever.tsx开关是否启用动画replayAnimationLever.tsx动作按钮触发动画重放replayKey 1streamWindowLever.tsx滑块/数字流式数据窗口swapDataLever.tsx动作按钮切换数据集themeLever.tsx下拉选择明暗主题切换例如 animationDurationLever.tsx 内部用createRangeLever生成一个 range 输入绑定state.animationDuration并映射回{ ...state, animationDuration }replayAnimationLever.tsx 则用createActionLever生成一个▶ Replay animation按钮点击后replayKey 1。若某个控制项很可能被多个示例复用就应该把它加进 gallery而不是在每个示例文件里临时造一套 UI。自定义 lever 的五种构造器如果 gallery 中没有合适的控制项可以使用 Levers.tsx 提供的构造器自己定义。LeverTState类型要求提供key与一个接收{ state, setState, htmlId }的组件htmlId应绑定到输入元素上以关联labelcreateActionLever按钮型点击触发一次动作如重放动画createRangeLever范围滑块支持min/max/step与可选的formatValue格式化显示值createNumberLever数字输入框同样支持min/max/stepcreateSelectLever下拉选择通过options: ReadonlyArray{ value, label }提供选项选中值必须是字符串createCheckboxLever复选框绑定布尔值。仓库中的真实范例是 LegendPositionExample.tsx它定义了ControlsState { position, layout, offset }用createSelectLever提供 13 种图例位置与 3 种布局选项用createNumberLever提供 0–100 的 offset然后在组件内部通过const { position, layout, offset } { ...defaultControlsState, ...props }合并默认值合并逻辑见该文件。控制状态的硬性要求控制状态必须保持可序列化serializable只存index | append、a | b这类简单键值再把键映射到示例组件内部的运行时函数或数据集Levers 是可选的并非每个示例都需要交互控制。可视化回归测试VR Test官方强烈建议为每个新示例配套编写 VR 测试。所有官网示例的 VR 测试都放在test-vr/tests/www/目录下测试文件命名为YourExampleName.spec-vr.tsx。一个完整的 VR 测试文件如下摘自 SKILL.mdimport * as React from react; import { test, expect } from playwright/experimental-ct-react; import TooltipStylesExample from ../../../www/src/docs/exampleComponents/Tooltip/TooltipStylesExample; test(TooltipStylesExample, async ({ mount }) { const component await mount(TooltipStylesExample /); await expect(component).toHaveScreenshot(); });仓库的 VR 测试基础设施位于 test-vr/ 目录配置见 test-vr/playwright.config.ts测试运行基于playwright/experimental-ct-reactPlaywright Component Testing。编写 VR 测试的关键注意点路径映射测试文件必须使用相对路径指回www/src/...如上面的../../../www/src/docs/exampleComponents/...结构约束Playwright CT 要求组件从独立文件中导入不能在测试文件内联声明组件Props 传递如果示例不接受 props直接ExampleComponent /挂载即可如果示例接受 props如 levers/controls 相关则需要按CodeEditorWithPreview的传参方式原样传入保证测试与真实页面行为一致截图生成生成截图需要 Docker而当前环境可能并未配置 Docker。需要提醒使用者必须在本地生成截图并提交到仓库VR 截图存放于 test-vr/snapshots/tests/该目录已收录 1000 张 PNG 基线截图。与示例的数据稳定性配合VR 测试能稳定工作的前提正是前面提到的generateMockData(length, seed)seed 固定后每次渲染数据一致toHaveScreenshot()才能与仓库中的基线截图逐像素比对。这也解释了为什么 SKILL.md 明确建议示例使用 seed 生成数据。完整开发流程小结结合 SKILL.md 与仓库实现一个示例从创建到上线的完整链路为创建示例文件在 www/src/docs/exampleComponents/ 下新建单文件组件只导入recharts公共 API 与注入依赖用generateMockData(length, seed)生成稳定数据默认导出组件并挂上RechartsDevtools /可选添加交互控制定义defaultControlsState与levers优先复用 gallery lever接入文档在指南或 API 文档如 www/src/components/GuideView/ 下的各指南页面中用CodeEditorWithPreview包裹示例传入Component、sourceCode?raw导入与stackBlitzTitle编写 VR 测试在 test-vr/tests/www/ 下创建YourExampleName.spec-vr.tsx按 Playwright CT 规范挂载示例并断言截图生成并提交基线截图在配置了 Docker 的本地环境运行 Playwright 生成截图将其提交到仓库test-vr/snapshots/tests/使 CI 与本地都能进行稳定的回归比对。通过这条流水线Recharts 官网的每一个示例都同时满足可读源码清晰、可玩Controls 交互、可验VR 回归三个标准而这套范式也可以直接迁移到你自己的 Recharts 图表组件库或文档站点建设中。【免费下载链接】rechartsRedefined chart library built with React and D3项目地址: https://gitcode.com/GitHub_Trending/re/recharts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考