Back to Details

layerchart

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LayerChart Skill

LayerChart 技能文档

LayerChart is a comprehensive Svelte visualization framework built on Layer Cake, providing composable components for creating responsive, interactive charts across multiple visualization types.
LayerChart 是一个基于 Layer Cake 构建的全功能 Svelte 可视化框架，提供可组合的组件，用于创建跨多种可视化类型的响应式交互式图表。

Core Architecture

核心架构

LayerChart operates on a component-based, data-driven philosophy. The library provides three primary categories of components:
Data-Driven Components render visual marks directly from data (Area, Bars, Spline, Pie, Sunburst, Treemap, Sankey, etc.). These components automatically handle scale transformations through LayerCake's context.
Motion-Enabled SVG Primitives (Rect, Circle, Arc, Group, Line, Path) provide low-level drawing utilities with built-in Svelte transition support for animated data updates.
Utility Components handle legends, tooltips, pan/zoom interactions, annotations, and layout operations (hierarchy, geo projections).
LayerChart 遵循基于组件、数据驱动的设计理念。该库提供三类核心组件：
数据驱动组件 直接从数据渲染可视化标记（区域图、柱状图、样条图、饼图、旭日图、树状图、桑基图等）。这些组件通过 LayerCake 的上下文自动处理尺度转换。
支持动效的 SVG 原语（矩形、圆形、弧形、组、线条、路径）提供底层绘图工具，内置 Svelte 过渡支持，可实现数据更新的动画效果。
工具组件 处理图例、工具提示、平移/缩放交互、注释以及布局操作（层级、地理投影）。

Visualization Types

可视化类型

  • Cartesian: Bar, Area, Stack, Scatter, Histogram, ClevelandDotPlot, BarStack, BarGroup
  • Radial: Pie, Arc, Sunburst, Threshold
  • Hierarchical: Pack, Tree, Treemap, Partition
  • Graph: Sankey, Link, Graph utilities
  • Geographic: Choropleth, Spike Map, Bubble Map, GeoTile, GeoPath, StateMap, AnimatedGlobe, Globe projections (Mercator, Azimuthal, Equal Earth, etc.)
  • 笛卡尔图：柱状图、区域图、堆叠图、散点图、直方图、克利夫兰点图、堆叠柱状图、分组柱状图
  • 径向图：饼图、弧形图、旭日图、阈值图
  • 层级图：打包图、树图、树状图、分区图
  • 关系图：桑基图、连接线、关系图工具
  • 地理图：等值区域图、尖峰地图、气泡地图、地理瓦片、地理路径、州地图、动画地球仪、地球投影（墨卡托、方位投影、等地球投影等）

Key Patterns

核心模式

Data Preparation

数据准备

Use LayerChart's data transformation utilities before passing to visualizations:
  • stack()
    - converts wide-format data into stacked series with baseline/top values
  • bin()
    - groups data into histogram bins with x0/x1 bounds
  • groupLonger()
    - pivots wide-format to long-format (one row per value)
  • flatten()
    - flattens nested arrays one level, with optional accessor
  • calcExtents()
    - calculates min/max across multiple fields, skipping nulls
在将数据传入可视化组件前，可使用 LayerChart 的数据转换工具：
  • stack()
    - 将宽格式数据转换为包含基线/顶部值的堆叠序列
  • bin()
    - 将数据分组到直方图区间，生成 x0/x1 边界
  • groupLonger()
    - 将宽格式数据转换为长格式（每行对应一个值）
  • flatten()
    - 将嵌套数组展平一级，支持可选的访问器
  • calcExtents()
    - 计算多个字段的最小值/最大值，跳过空值

Component Composition

组件组合

All LayerChart visualizations sit within a LayerCake wrapper that establishes scales and context. Child components access scales via Svelte's context API.
svelte
<LayerCake x="date" y="value" data={data} padding={{...}}>
  <Svg>
    <Area />
    <Line />
    <AxisX />
  </Svg>
  <Canvas>
    <Points />  <!-- High-performance canvas rendering -->
  </Canvas>
  <Html>
    <Tooltip />
  </Html>
</LayerCake>
所有 LayerChart 可视化都需包裹在 LayerCake 容器中，由其建立尺度和上下文。子组件通过 Svelte 的上下文 API 访问尺度。
svelte
<LayerCake x="date" y="value" data={data} padding={{...}}>
  <Svg>
    <Area />
    <Line />
    <AxisX />
  </Svg>
  <Canvas>
    <Points />  <!-- 高性能画布渲染 -->
  </Canvas>
  <Html>
    <Tooltip />
  </Html>
</LayerCake>

Interaction Patterns

交互模式

  • Tooltips: Position over data with snap-to-data options
  • Pan/Zoom: Built-in context utilities for interactive navigation
  • Highlighting: Hover states trigger visual emphasis (opacity, stroke changes)
  • Selection: Use reactive variables and event handlers for interactive filtering
  • 工具提示：可定位在数据上方，支持吸附到数据的选项
  • 平移/缩放：内置上下文工具，支持交互式导航
  • 高亮：悬停状态触发视觉强调（透明度、描边变化）
  • 选择：使用响应式变量和事件处理程序实现交互式过滤

Responsive Design

响应式设计

LayerChart automatically handles responsive layouts via 
padding
configuration and container dimensions. Components reactively update when data or scales change.
LayerChart 通过 
padding
配置和容器尺寸自动处理响应式布局。当数据或尺度变化时，组件会响应式更新。

Common Implementation Tasks

常见实现任务

Bar Charts: Use 
Bars
component with 
x
as categorical field. Stack with 
BarStack
or group with 
BarGroup
for multi-series.
Time Series: Configure 
xScale={scaleTime()}
with temporal data. Use 
AxisX
with 
tickFormat
for readable date labels.
Geographic Visualizations: Select appropriate projection (Mercator for web maps, Azimuthal for polar), use 
GeoPath
for boundaries, 
Choropleth
for value mapping.
High-Volume Data: Render marks via Canvas instead of SVG for 5000+ points. Layer SVG axes/legends with Canvas for hybrid rendering.
Stacked/Grouped Series: Use 
stack()
utility to transform data, then render via 
AreaStack
/
BarStack
components.
柱状图：使用 
Bars
组件，将 
x
设置为分类字段。使用 
BarStack
实现堆叠效果，或使用 
BarGroup
实现多序列分组。
时间序列：将 
xScale={scaleTime()}
与时间数据配合使用。为 
AxisX
设置 
tickFormat
以生成易读的日期标签。
地理可视化：选择合适的投影（Web 地图用墨卡托投影，极地用方位投影），使用 
GeoPath
绘制边界，使用 
Choropleth
实现值映射。
大数据量场景：当数据点超过 5000 个时，使用 Canvas 而非 SVG 渲染标记。可采用混合渲染方式：用 Canvas 渲染标记，用 SVG 渲染坐标轴/图例。
堆叠/分组序列：使用 
stack()
工具转换数据，然后通过 
AreaStack
/
BarStack
组件渲染。

Performance Considerations

性能考量

  • Canvas rendering for 5000+ points (~60fps on modern hardware)
  • SVG for interactive elements and animations (<500 points recommended)
  • Hybrid approach: Canvas for marks + SVG for axes/legends
  • Scale calculations are reactive—only update scales when data/domain changes
  • Memoize expensive data transforms outside component lifecycle
  • 数据点超过 5000 个时使用 Canvas 渲染（现代硬件上约 60fps）
  • SVG 适用于交互元素和动画（建议数据点少于 500 个）
  • 混合方式：Canvas 渲染标记 + SVG 渲染坐标轴/图例
  • 尺度计算是响应式的——仅在数据/定义域变化时更新尺度
  • 在组件生命周期外缓存开销较大的数据转换操作

Styling and Customization

样式与自定义

All primitive components support standard SVG/Canvas attributes (stroke, fill, opacity, strokeWidth). Use Svelte's reactive statements for conditional styling based on interaction state or data values.
Gradient fills, patterns, and clipping available via 
ClipPath
, 
RectClipPath
, 
CircleClipPath
components with SVG 
<defs>
.
所有原语组件都支持标准 SVG/Canvas 属性（描边、填充、透明度、描边宽度）。可使用 Svelte 的响应式语句，根据交互状态或数据值实现条件样式。
可通过 
ClipPath
、
RectClipPath
、
CircleClipPath
组件结合 SVG 
<defs>
实现渐变填充、图案和裁剪效果。

Integration Notes

集成说明

  • Works seamlessly with D3 scales (linear, time, ordinal, log, threshold)
  • Supports multiple render contexts in same chart (SVG + Canvas + HTML)
  • Fully accessible with ARIA attributes on SVG elements
  • SSR-compatible for server-side rendering in SvelteKit
  • Zero external dependencies beyond Svelte and d3-array utilities
  • 可与 D3 尺度（线性、时间、序数、对数、阈值）无缝协作
  • 支持在同一图表中使用多种渲染上下文（SVG + Canvas + HTML）
  • 完全支持无障碍访问，SVG 元素带有 ARIA 属性
  • 支持 SSR，可在 SvelteKit 中实现服务端渲染
  • 除 Svelte 和 d3-array 工具外，无其他外部依赖