LineChart 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

用折线展示数据变化趋势，支持多序列、面积填充、实线与虚线，以及坐标轴、网格和节点样式。

使用选择

用于连续数据或时间趋势。类别比较用 BarChart；数据点、轴、提示与颜色通过公开图表配置声明。

• 通过 series 提供数据；组件不生成示例数据，xLabels 与数据点应保持对应。

• loading 保留轴与画布，等待结束后展示数据；HoverPanel 默认开启，颜色和格式使用图表公开配置。

• 根默认可访问名称随 LocaleProvider 切换，使用 lineChart.name；显式 aria-label 优先。数据单元格组使用 lineChart.cells。业务名称、数据值与数字格式保持调用方内容。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Frame } from '@snowui-design-system/components';	import { LineChart } from '@snowui-design-system/components';</script> <LineChart series={[{ name: 'Component pages', data: [1280, 1460, 1390, 1720, 1880, 2140, 2360], color: 'Primary', strokeWidth: 3 }, { name: 'Quick Start', data: [620, 710, 680, 840, 920, 1040, 1180], color: 'var(--secondary-purple)', strokeStyle: 'dashed' }]} xLabels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']} width="100%" height={280} yTicks={[0, 500, 1000, 1500, 2000, 2500]} yTickFormatter={(value) => value < 1000 ? String(value) : `${value / 1000}K`} showYAxis showGrid showHoverPanel hoverPanelVariant="surface" />

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

HoverPanel 使用共享三列布局；圆点—名称优先 --gap-1，名称—数值优先 --gap-2，两处均至少保留 4 CSS px，并跟随 LTR / RTL 逻辑方向。默认 16px 根字号下仍为 4px / 8px，较大 Token 保留；面板纵向分区和图表中心注释不套用此下限。

设计原则

• Chart 原子组件: LineChart 只负责折线图本体，不内置标题、卡片背景、legend 或 toolbar。

• 无内置示例数据: LineChart 不在组件内部模拟业务数据；示例、业务页面或外层组合组件必须显式传入 series 与 xLabels。

• Area 不拆分: Area 是 LineChart 的序列填充形态；通过 series[].area 开启，不单独拆 AreaChart。

• 多序列: 一张图可同时渲染实线、虚线、ChartSpec 默认色序和不同 marker 策略。

• 坐标轴内建: 横坐标、纵坐标、网格线属于 LineChart 形态能力，放在组件内。

• Y 轴自适应宽度: Y 轴不使用固定预留宽度；标签区宽度等于当前最宽可见标签的实际渲染宽度，标签右边缘与绘图区起点固定保留 12px。标签变宽时仅按实际增加的宽度压缩绘图区。

• 动态顶部安全区: 线条或 marker 的最高可见边缘距组件顶部至少 8px；显示 Y 轴时至少 16px。顶部数值 label 不额外增加安全区，仍保持在节点上方 4px，必要时可溢出绘图区顶边；marker 半径的安全区不依赖是否显示数值 label。显示 X 轴时底部仅保留 8px 标签间距和 16px 标签高度。

• 分类轴点位模型: 横坐标默认使用 edge 模式，首尾数据点与首尾 label 中心都对齐到绘图区两端；也可切换为 cell 模式让节点位于等宽分类 cell 中心。label 放不下时按当前点位模式重新计算并自动减少中间坐标和数据点，至少保留首尾。

• 节点可定制: 序列和单点都可配置 marker；单点配置优先级高于序列配置。

• hover label: 默认 hover / focus 节点时在点上方 4px 显示数值 label，不因触及绘图区顶边改变位置；同时节点反色并在节点后方显示 0.5px 黑色竖线。字号 12px、常规体，默认 Black/100%。数字格式消费 NumberFormats.md，默认非整数显示 2 位小数。alwaysShowHoverLabel 可让数值 label 常显。

• 圆角转折线: LineChart 只保留圆角转折线；主体保持直线，只在折点处按 cornerRadius 生成局部圆角，cornerRadius=0 时为直线。

• Chart 通用出现动效: 每条序列自身绘制时长固定为 1000ms，与 CircularChart 一致；线与 Area 从左到右缓出揭示。多序列按 360ms 延迟依次启动，每条序列拥有独立缓出时间轴；marker 在线条 reveal 到对应点位时立即出现，不做透明度缓动。

2.1 Props

其余未声明属性会透传给根层 Frame。

2.2 组件方法

2.3 数据结构

type LineChartColor = ChartColor;type LineChartStrokeStyle = "solid" | "dashed";type LineChartXAxisMode = "cell" | "edge"; interface LineChartMarkerConfig {  size?: number | string;  color?: LineChartColor | "line";} interface LineChartPointMarkerConfig {  size?: number | string;} interface LineChartPoint {  label?: string;  value: number;  marker?: boolean | LineChartPointMarkerConfig;  valueFormat?: NumberFormatOptions;} interface LineChartSeries {  name: string;  data: (number | LineChartPoint)[];  color?: LineChartColor;  strokeWidth?: number | string;  strokeStyle?: LineChartStrokeStyle;  cornerRadius?: number | string;  markers?: boolean | LineChartMarkerConfig;  guides?: boolean;  area?: boolean;  valueFormat?: NumberFormatOptions;}

数值格式优先级：labelFormatter → point.valueFormat → series.valueFormat → 组件 valueFormat → NumberFormatContext → NumberFormats 默认值。

颜色优先级：series[i].color → colors[i] → colorMode 对应回退色。默认 sequence 色序与 ChartSpec 一致。color 可作为单色模式主色，传入后 monochromeFade 默认从该颜色 100% 均匀递减到最后一条序列 20%，monochrome 默认所有未自定义序列使用该颜色；未传 color 时，monochromeFade 默认 Primary，monochrome 默认 Black4。颜色支持 SnowUI 语意色、普通 CSS 颜色、CSS 变量、linear-gradient(...) 字符串和渐变对象。

纵坐标刻度说明：

• 未传 yMax / yTicks 时，domain 上限等于 series 的实际最大数据值，nice ticks 只生成到不高于该值的最后一个易读刻度；最高点可以高于最后一条网格线。

• 正数数据默认包含 0 作为纵轴起点；存在负数时使用数据最小值参与计算。

• 步长按 1 / 2 / 5 × 10^n 取整，目标刻度数量由 yTickCount 控制。

• yMaxLabelCount 会限制纵坐标 label 数量；未传 yTicks 时优先以 min(yTickCount, yMaxLabelCount) 生成 nice ticks，传入大量 yTicks 时再按等步数抽稀显示。

• yMin / yMax 可作为 domain 边界提示；yTicks 显式传入时优先级最高。

• yMin / yMax 不会把超出范围的数据夹到边界；超出 domain 的折线与 Area 会先按 Y domain 生成可见片段，边界处保留圆头端点，marker 与 guide 仅在点值位于当前 Y domain 内时显示。

• showGrid && showXAxis 时，水平线总数默认为 yTickCount=6，其中最底下一条由 x 轴基线承担，避免底线重复绘制。

Area 填充说明：

• area: true 在序列使用普通颜色时生成纵向渐变，顶部不透明度为 0.04（4%），底部渐变到 0（全透明）。序列 color 显式使用 CSS 渐变或 ChartGradient 对象时，Area 直接沿用其色标及透明度；两个相同颜色且不透明的色标可形成实色面积。

• Area 不提供独立于线条的颜色、透明度、渐变或 baseline 配置；通过序列 color 同时影响线条和面积，通过纵轴 domain 影响 baseline。

• area 与 strokeStyle 独立，可组合出“虚线 + 半透明面积填充”。

Marker 说明：

• marker 默认关闭；需要节点时通过 series[].markers 或 point.marker 显式开启。

• markers: true 使用 Figma Dot 结构：整体 8x8，由下层 Black/100% 圆与上层 White/100% 圆两层组成；下层圆为 8x8，上层圆为 4x4，分别使用 var(--black-100) 与 var(--white-100)。

• markers.size / point.marker.size 只做整体等比缩放。

• markers.color 只替换设计稿中的下层 Black/100%；可传任意颜色，也可传 "line" 跟随当前线色。

• 单点 point.marker 只允许改尺寸或关闭，不允许在同一条线上定义不同颜色的节点。

• marker hover / focus 时下层圆变为 White/100%（var(--white-100)），上层圆变为 Black/100%（var(--black-100)），并在节点后方显示一条贯穿绘图区的竖线；竖线粗细 0.5px、圆头、Black/100%。

• marker 其他结构、下层/上层比例与 hover 竖线不提供自定义。

线形说明：

• LineChart 只保留圆角转折线，主体为直线段，只在中间折点处按 cornerRadius 截短前后线段并生成局部圆角。

• cornerRadius=0 时不生成圆角，表现为普通直线折线。

• strokeStyle="dashed" 使用 Figma stroke 设置：dash 2、gap 4、round cap。

布局模型

主布局模型:内禀原子布局。

• 根层为 Frame，内部为单个 SVG 绘图区。

• 根层直接观察最终显示尺寸并重算 SVG 坐标；width="100%" / height="100%" 不要求页面回传容器尺寸。

• 横向分类轴按 max(xLabels.length, ...series.data.length) 计算点位数量；cell 模式节点位置为 bounds.left + (plotWidth / count) * (index + 0.5)，edge 模式节点位置为 bounds.left + (plotWidth / (count - 1)) * index，单点时居中。

• X 轴 label 使用当前点位间距作为 cell 宽度，文字居中且单行省略；整体高度为 16px。

• edge 模式下首尾 label 的中心与首尾数据点同 x 坐标，label cell 允许向绘图区外侧延伸。

• X 轴 label 自动显示规则：按最终字体实测完整文字宽度与当前 xAxisMode 的原始数据位置判断，相邻可见文字至少间隔 4px。抽稀只减少 label，不删除或重排数据点、折线路径、marker、guide 与命中 cell。保留索引必须形成等差步数；若首尾两个完整 label 仍放不下，则隐藏全部 X label。

• Y 轴 label 抽稀规则：自动生成刻度时优先通过 yTickCount / yMaxLabelCount 生成合适数量；显式传入 yTicks 或纵向空间不足时，按首尾保留、等步数的规则减少显示 label，水平网格线跟随可见 Y label。

• X 轴 label cell 顶部到最下面 x 轴基线的间距为 8px。

• 绘图区顶部由共享内容感知规则计算：线条宽度的一半或当前最大 marker 半径作为图形向上溢出量；普通图形保持 8px 安全距离，Y 轴顶刻度至少需要 16px。顶部数值 label 不增加该值，继续保持节点上方 4px 并可溢出绘图区顶边；marker 的溢出量始终计入，不依赖 label 是否显示。有 X 轴时 bottom=24px，只包含上述 8px 间距和 16px label 高度；无 X 轴时 bottom=0。

• Y 轴标签区宽度由全部可见 Y label 中最宽文本的实际 SVG 渲染宽度决定，不使用固定 bounds 或字符数量估算；label 右边缘到绘图区线段起点的间距固定为 12px。例如 formatter 输出 100000 时，绘图区只按该文本比短刻度新增的实际宽度缩小，固定间距不变。

• 不接入三槽位协议，不承担通用子元素排列。

详见 LayoutProtocol.md §12.7（源码参考：specs/maintainers/LayoutProtocol.md）。

无障碍与 Frame 集成

• 交互根使用 role="group" 和 aria-label="折线图"（zh-CN 默认，随 locale 切换），让内部命中项保留独立语义。

• 每个 marker 使用独立 aria-label，内容包含序列名、横坐标标签和值。

• marker 内部包含透明命中圆，保证键盘焦点与鼠标命中不只依赖可见圆点半径。

• marker 可见层不接管 pointer events，白色中心、黑色外圈与透明命中圆统一由命中圆触发；默认命中区域不小于 16x16。

• 独立使用或接入 ChartGroup 时均支持 hoverMode="cell"；cell 命中区按分类点位中心左右半格覆盖绘图区，对应分类点位的 marker 响应 hover，marker 自身命中区仍独立保留。

• loading 保留完整画布与坐标结构，只把折线、面积和 marker 恢复到出现动效起点；根 Frame 明确关闭 Skeleton。空 series={[]} 可配合 xLabels、yMin、yMax 先建立最终坐标。

• 显式传入 enableResponsive / enableContext / enableScaleObserver / enableDefaultMotion。

• class、style 与未声明属性透传到根层 Frame。

图层与动效

SVG 图层从下到上为：

1. defs: 颜色渐变、Area 渐变、序列 reveal clipPath。

2. grid / axis layer: 水平网格线和 x 轴基线。

3. base layer: showBaseLayer=true 时绘制完整 Area 与折线路径的同色 4% 占位层，不参与出现动效；默认不渲染。

4. area layer: 真实 Area 路径，按对应序列 clipPath 从左到右揭示。

5. guide layer: 节点垂直辅助线，跟随对应序列进度显隐。

6. series layer: 真实折线路径，按对应序列 clipPath 从左到右揭示。

7. marker layer: 节点点、hover 竖线与透明命中圆，在线条 reveal 到对应点位时立即显隐。

8. axis label layer: 横纵坐标文本。

出现动效沿用 Chart 通用 API：

• appearMotion={false} 时直接显示完整图表。

• 默认进入视口后自动播放，播放顺序按 series 数组顺序。

• 每条序列使用 appearance-timeline.ts 的 fillProgress 与 opacityProgress。

• 每条序列自身绘制时长固定为 1000ms，与 CircularChart 一致。

• 多序列默认相隔 360ms 启动；第一条序列立即出现，后续序列依次延迟启动。

• fillProgress 控制从左到右的 reveal clip 宽度，并使用缓出；LineChart 当前使用 easeOut power 6。

• opacityProgress 控制真实线、Area 和辅助线的透明度，并使用同一缓出。

• marker 不消费 opacityProgress；线条 reveal 边界到达该点 x 坐标时立即出现。

• 支持 appearanceProgress 受控时间轴、滚动时间轴和 replay() / resetAppearance() / reverseAppearance() 方法。