visx 示例沙箱sandboxes目录完全指南独立可运行的 React D3 图表 Demo 结构与 CodeSandbox 导入实践【免费下载链接】visx visx | visualization components项目地址: https://gitcode.com/gh_mirrors/vi/visx导读在 visx 仓库中packages/visx-demo/src/sandboxes 目录集中存放了 40 个独立、自包含的 visx 使用示例Examples覆盖从基础柱状图、面积图到复杂的地图投影、力导向网络、词云与 xychart 复合图表的全部功能模块。这些示例既是理解每个 visx 子包 API 的最佳入门材料也是可以被 CodeSandbox 的 import from GitHub 功能直接加载、在线运行、即时修改的最小化可运行项目。本文将基于 sandboxes/README.md 的核心说明结合仓库源码逐层拆解该目录的目录结构、每个示例的工程文件约定、依赖声明方式、Gallery 联动机制并给出本地运行与在线导入的完整操作路径。一、sandboxes 目录定位什么是可独立运行的示例README 原文明确了两点核心定位This directory contains examples ofvisxusage. Each folder is a complete standalone project, and is imported using the Code Sandbox import from GitHub feature.翻译并展开即目录用途存放 visx 的实际使用示例是仓库内功能演示Gallery/Demo 页面的源码素材库。示例形态每个子文件夹都是一个完整的独立项目complete standalone project——它自带package.json、入口文件、样式文件和示例组件不依赖 visx-demo 应用本身的其他代码可以脱离整个 monorepo 单独安装、构建与运行。消费方式这些文件夹被设计为可通过 CodeSandbox 的import from GitHub从 GitHub 导入功能直接加载实现在线编辑与运行。从源码结构可以推断这种每个示例自成项目的约定是 visx 团队刻意为之既服务于官网 Gallery 页面的在线 Playground 体验也方便贡献者把单个示例复制出去做最小化复现bug report。二、目录全景template 模板 44 个示例 联动工具list该目录packages/visx-demo/src/sandboxes可以看到三类内容分类名称作用模板template/新建示例时的空白脚手架给出最小工程约定示例visx-annotation/、visx-area/、visx-axis/、visx-bargroup/、visx-bars/、visx-barstack/、visx-brush/、visx-chord/、visx-curve/、visx-delaunay-triangulation/、visx-delaunay-voronoi/、visx-dendrogram/、visx-dots/、visx-drag-i/、visx-drag-ii/、visx-geo-albers-usa/、visx-geo-custom/、visx-geo-mercator/、visx-glyph/、visx-gradient/、visx-heatmap/、visx-legend/、visx-linktypes/、visx-network/、visx-pack/、visx-pattern/、visx-polygons/、visx-radar/、visx-radial-bars/、visx-responsive/、visx-sankey/、visx-shape-line-radial/、visx-shape-pie/、visx-shape-splitlinepath/、visx-stacked-areas/、visx-stats/、visx-streamgraph/、visx-threshold/、visx-tooltip/、visx-tree/、visx-treemap/、visx-voronoi/、visx-wordcloud/、visx-xychart/、visx-zoom-i/等覆盖各 visx 子包的独立可运行示例工具exampleToVisxDependencyLookup.ts构建 Gallery 页面示例 ↔ visx 子包依赖映射表2.1 命名规律目录名统一以visx-为前缀后缀即所演示的 visx 子包或能力如visx-area演示visx/shape的AreaClosedvisx-xychart演示复合图表包。同一能力存在多个变体时用罗马数字或修饰词区分例如visx-drag-i、visx-drag-iivisx-bargroup与visx-bargroup-horizontalvisx-shape-pie与visx-shape-line-radial。三、示例的标准工程骨架4 个约定文件每个示例文件夹内部结构高度一致部分示例会多出findNearestDatum.ts、data.ts之类的辅助模块核心固定为 4 个文件visx-xxx/ ├── package.json # 独立依赖声明可单独安装 ├── index.tsx # React 入口挂载 Example ├── Example.tsx # 示例组件本体接收 width/height props └── sandbox-styles.css # 示例专属样式3.1 入口文件 index.tsx统一的挂载模式以 visx-xychart/index.tsx 为例import React from react; import { createRoot } from react-dom/client; import { ParentSize } from visx/responsive; import Example from ./Example; import ./sandbox-styles.css; const root createRoot(document.getElementById(root)!); root.render( ParentSize{({ width, height }) Example width{width} height{height} /}/ParentSize, );要点使用 React 18 的createRoot从react-dom/client挂载到#root节点引入visx/responsive的ParentSize组件包裹Example将容器实际像素尺寸以width/height传入——这是所有示例都能自适应容器宽高的关键也解释了为什么每个示例的Example.tsx都要求width/height两个 props引入同目录的sandbox-styles.css保证样式隔离。3.2 模板 Example.tsx组件的签名约定template/Example.tsx 展示了每个示例组件必须满足的最小接口import React from react; type Props { width: number; height: number; }; export default function Example({ width, height }: Props) { return ( Example div width em{width}px/em height em{height}px/em /div / ); }可见约定为默认导出一个接收{ width, height }的函数组件。新建一个示例时直接复制template/目录并替换Example.tsx的实现即可其余工程化样板无需改动。3.3 独立 package.json依赖自包含示例的package.json完全独立不引用 monorepo 内部路径因此可以被 CodeSandbox 单独解析。以 visx-annotation/package.json 为例{ name: visx/demo-annotation, description: Standalone visx annotation demo., main: index.tsx, private: true, dependencies: { babel/runtime: ^7.8.4, types/react: ^18, types/react-dom: ^18, visx/annotation: latest, visx/mock-data: latest, visx/responsive: latest, visx/scale: latest, visx/shape: latest, visx/vendor: latest, react: ^18, react-dom: ^18, react-scripts-ts: 3.1.0, typescript: ^3 }, keywords: [visualization, d3, react, visx, annotation] }从中可以观察到的工程约定包名统一为visx/demo-能力名如visx/demo-xychart、visx/demo-annotationprivate: true这些示例包不会被发布到 npm仅供演示与导入使用main指向index.tsx入口即 TSX 源码由 CodeSandbox 的构建链直接处理固定基础依赖react/react-dom^18、types/react、types/react-dom、react-scripts-ts3.1.0基于 Create React App TS 的脚本、typescript^3以及babel/runtime按需声明 visx 子包visx/*依赖均使用latest个别版本锁定如 xychart 示例中的visx/curve: 1.0.0并额外引入visx/mock-data示例数据、visx/responsiveParentSize等辅助包keywords 保留项目关键词并在末尾追加能力词如annotation便于检索。复杂的示例会引入更多依赖例如 visx-xychart/package.json 额外声明了visx/curve、visx/glyph、visx/mock-data、visx/pattern、visx/react-spring以及react-spring/web用于演示 xychart 与动画、纹理填充的组合能力。四、Gallery 联动exampleToVisxDependencyLookup.ts 如何工作示例目录不仅是独立的 CodeSandbox 项目还与 visx-demo 应用的 Gallery 页面联动。枢纽文件是 exampleToVisxDependencyLookup.ts其工作流程如下批量导入静态import每个示例的package.json共 40 个含 Gallery 的TextTile包提取 visx 依赖调用../components/util/extractVisxDepsFromPackageJson从每个示例的依赖中筛选出visx/*子包名建表生成{ 示例包名: SetVisxPackage }映射exampleToVisxDependencyLookup记录哪个示例用到了哪些 visx 子包汇总visxPackages导出全部示例涉及到的 visx 子包去重排序列表供 Gallery 做按包筛选。由此Gallery 页面可以做到按 visx 子包过滤示例选中visx/annotation就会列出所有依赖它的示例点击即可跳转到对应 CodeSandbox 在线运行。从源码结构可以推断新增示例后只要把示例的package.json加入该文件的examples数组映射关系即自动建立无需维护重复的元数据。五、两种消费方式在线导入与本地运行5.1 通过 CodeSandbox import from GitHub 在线运行这是 README 指定的主要消费路径。CodeSandbox 支持输入一个 GitHub 仓库路径或目录路径来导入项目打开 CodeSandbox 的导入页面选择 import from GitHub输入 visx 仓库地址并在路径中定位到具体示例目录例如packages/visx-demo/src/sandboxes/visx-xychartCodeSandbox 会读取该目录下的package.json、index.tsx并自动安装依赖、编译运行由于每个示例都是自包含项目main指向index.tsx样式、数据、组件都在目录内导入后即可直接看到图表并在线修改代码。适用前提与限制该功能依赖 CodeSandbox 对 GitHub 仓库目录的解析能力且示例依赖安装以各示例package.json中声明的版本多数为latest为准在线环境的 React/TypeScript 版本以声明为准本仓库示例为 React 18 TypeScript 3 react-scripts-ts。5.2 本地运行单个示例由于示例是独立项目可以将其目录复制到本地任意位置后像普通 CRA 项目一样运行# 以 visx-xychart 为例 cd packages/visx-demo/src/sandboxes/visx-xychart npm install # 或 yarn npm start # 由 react-scripts-ts 启动开发服务器说明示例依赖中的visx/*多为latest会从 npm 拉取已发布版本而非本仓库的本地构建产物因此本地运行主要用于体验与调试示例本身。若需运行仓库内最新源码的完整演示应用应使用根目录 package.json 的脚本如yarn start启动 visx-demo来浏览所有示例的聚合页面。六、从模板到新示例最小操作路径综合 template 与现有示例的结构新增一个示例的推荐路径为复制 template/ 为visx-能力名/编辑package.json修改name为visx/demo-能力名、更新 description 与 keywords并补充该示例实际用到的visx/*依赖参考visx-annotation、visx-xychart等现有声明在Example.tsx中实现接收{ width, height }的图表组件在 exampleToVisxDependencyLookup.ts 的examples数组中注册该示例的package.json使 Gallery 联动自动生效在visx-demo的 Gallery 数据见 visx-demo/src/components 与 visx-demo/src/pages中登记入口即可出现在演示站点的示例列表中。七、小结sandboxes目录是 visx 仓库中示例即独立项目工程思想的直接体现每个示例自包含package.json index.tsx Example.tsx css可被 CodeSandbox import from GitHub 直接加载统一的组件签名({ width, height })配合visx/responsive的ParentSize保证示例在任何容器尺寸下自适应通过exampleToVisxDependencyLookup.ts与 Gallery 联动实现按 visx 子包检索示例template/ 提供零成本起步模板让社区贡献者可以快速添加新示例。对开发者而言阅读 sandboxes/README.md 后最直接的收益是想快速验证某个 visx 子包 API 时无需搭建完整工程直接定位对应visx-*目录即可获得一份可运行的最小示例想深入源码则可从各示例的Example.tsx出发对照 packages 下对应子包的src/实现逐一印证。【免费下载链接】visx visx | visualization components项目地址: https://gitcode.com/gh_mirrors/vi/visx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考