DitherChart | Tuff Docs

用法

TxDitherChart 位于现有 @talex-touch/tuffex/charts 入口，不另建图表包。传入真实 series、nodes 或 cells；空数据只显示空状态，不自动填充演示值。periods 接受带名称的完整数据快照，不通过倍率生成业务数据。

遍历全部来源图形

演示包含11个目录图表、8个额外图形与卡片、10种纹理、来源等价说明以及书页与指标组合。周期、系列过滤、仪表/存储/指标选择、悬停、键盘和范围输入都操作当前画面的数据。点击缩略图可进入对应完整图表。

示例加载中...

数据与周期快照

环图、设备、漏斗和计划卡片使用系列的 value；未传 value 时使用点值总和。
堆叠、支付和柱图使用 series[].data。点的 label 是类别标识，同名类别会把不同支付渠道对齐到同一分支。
增长、收入、成员和迷你图使用有序 { label, value } 点。日期游标以点索引为准，组件内部不读取当前日期。
半圆与径向仪表使用 value / capacity，容量默认100。存储条使用同样比例，并显示调用方提供的容量与单位。这些图例的点击是选择指标，而不是隐藏系列。
气泡与散点使用 nodes，x、y 是0–100坐标。气泡的y轴向下增长，半径按逻辑CSS像素计算；散点的y轴向上增长，默认绘制较小的点簇。
活动与时段矩阵使用显式、从0开始的 row、column。在线矩阵按输入顺序排列细状态条，容器变窄时换行；读取 up、degraded、down，未传状态时使用0–1数值。

每个周期有 id、label，可选 series、nodes、cells。传入的集合替换对应基础集合；省略的集合沿用基础集合，显式空数组保持为空。所有受控模型都可省略，此时周期、过滤、选择、悬停与游标由组件本地维护。

最佳实践

为系列、节点和单元格提供稳定ID与有意义的标签。日期游标需要稳定的点顺序。periods 应传真实服务端快照，不在界面中制造业务成功或随机值。
activeKeys 控制可见系列，selectedSeries 控制仪表、存储或迷你图指标，二者含义不同。图例悬停/聚焦只高亮；点击、空格和Enter执行实际控制动作。
compact 只移除卡片文案、过滤器和图例，不更换图形或数据。紧凑图形需要独立操作时，在外部提供完整控制。
color 优先使用token，默认使用随主题变化的单色墨色梯度，hover不补间颜色。formatValue 负责货币、语言和单位；组件不虚构变化幅度、收入或服务状态。
animated=false、离屏、文档隐藏、KeepAlive失活和减少动态效果都会暂停逐帧循环，数据与操作仍可用。SVG纹理直接绘制真实几何，不运行Canvas动画循环。

API 参考

属性

属性	类型	默认值	行为
`variant`	`DitherChartVariant`	`dither-donut`	下表19种独立图形之一。
`pattern`	`DitherPattern`	`pixel`	像素shader、有序Bayer抖动或8种SVG纹理。
`series`	`readonly DitherSeries[]`	`[]`	命名数值/点集合，不自动生成数据。
`nodes`	`readonly DitherNode[]`	`[]`	气泡/散点的位置、半径和tooltip数值。
`cells`	`readonly DitherCell[]`	`[]`	矩阵坐标、活动/在线数值。
`periods`	`readonly DitherPeriod[]`	`[]`	调用方提供的命名数据快照。
`period`	`string`	第一个周期ID	可选受控周期模型。
`activeKeys`	`readonly string[]`	全部系列/节点	可选受控可见性模型；`[]` 隐藏全部。
`selectedSeries`	`string`	第一个可见系列	控制半圆/径向仪表、存储和迷你图的指标选择。
`hover`	`DitherHover \| null`	本地悬停值	受控数据项，含 `id`、可选 `seriesId`、`label`、`value`。
`dateCursor`	`number \| null`	`null`	受控点索引，可由指针、键盘和范围输入更新。
`title`	`string`	`''`	标题与无障碍名称。
`description`	`string`	`''`	说明与无障碍描述。
`labels`	`DitherChartLabels`	英文标签	`empty`、`period`、`series`、`chart`、`total`、`capacity`、`less`、`more`、`cursor`；传入本地化文案。
`height`	`number`	`180`	绘图区CSS像素高度，至少32；宽度跟随容器。
`compact`	`boolean`	`false`	只显示图形的缩略图。
`animated`	`boolean`	`true`	活跃状态允许时播放数据插值和像素纹理。
`size`	`xs \| sm \| md \| lg`	`md`	内边距与分组间隔。
`maxValue`	`number`	按数据计算	柱图/面积图固定上界、矩阵强度上界、漏斗分母。
`showLegend`	`boolean`	`true`	非紧凑模式显示命名系列控制。
`indicator`	`dot \| line \| dashed`	`dot`	图例与tooltip标记结构。
`formatValue`	`(value, label, series?) => string`	英文数值格式 + 传入单位	摘要、图例、容量与tooltip共用格式化函数。

DitherSeries：id、label，可选 value、capacity、data: readonly { label, value }[]、color、unit、change。change 是调用方文案，不自动计算业务指标。DitherNode：id、label、x、y、value，可选 radius、color。DitherCell：id、label、row、column、value，可选 status。

变体与纹理

变体	固定来源渲染器	独立形态
`dither-donut`	`DitherDonutChart`	圆角、有间隔的计划扇区与径向密度像素。
`dither-stacked`	`DitherStackedChart`	区域渠道堆叠，支持渠道和分支高亮。
`dither-growth`	`DitherGrowthChart`	像素面积、静态底网格与日期游标。
`dither-heatmap`	`ActivityHeatmap`	居中的贡献日矩阵。
`dither-gauge`	`ServerGauge`	细半圆轨道与所选指标填充。
`dither-traffic`	`TrafficBubble`	带标签、漂浮的填充气泡簇。
`dither-funnel`	`DitherFunnelChart`	左对齐、逐阶段缩减的条形。
`dither-device`	`DeviceUsageChart`	连续设备环段，不等同于圆角计划扇区。
`dither-storage`	`StorageUsageChart`	容量轨道与所选资源填充。
`dither-revenue`	`RevenueLineChart`	实线折线与逐渐减弱的像素面积。
`dither-uptime`	`UptimeChart`	会换行的细日期状态条。
`dither-bar`	`DitherBarChart`	密度随高度变化的垂直柱。
`dither-radial`	`DitherRadialChart`	完整目标进度环与中央百分比。
`dither-scatter`	`DitherScatterChart`	小型点簇与连接趋势线。
`dither-heatmap-grid`	`DitherHeatmapGrid`	完整日/时段强度矩阵。
`dither-sparkline-matrix`	`DitherSparklineMatrix`	可选择的指标矩阵与像素面积。
`members-growth`	`MembersGrowthChart`	成员摘要、较强底像素、日期与游标。
`payments`	`PaymentsChart`	支付摘要、有间隔的圆角渠道与分支/渠道读数。
`plan-card`	`ChartCard`	计划摘要、分布与数值/百分比明细。

DITHER_CHART_VARIANTS、DITHER_PATTERNS 导出完整类型列表。纹理为 pixel、ordered、dot、hatched、duotone、striped、dotted、area-gradient、primary-gradient、noise。有序模式使用真实4×4 Bayer阈值矩阵；SVG模式分别使用不同 <pattern>、<linearGradient> 或裁切噪声filter，不是给同一种填充换名。

事件与插槽

事件	参数
`update:period`、`period-change`	周期ID。
`update:activeKeys`	可见ID数组。
`update:selectedSeries`	所选指标ID。
`update:hover`	`DitherHover \| null`。
`update:dateCursor`	点索引或 `null`。
`select`	指针点击或Enter/空格选中的数据项。

插槽：header({ total, period })、tooltip({ hover })、footer({ dataset })。tooltip复用现有charts core上下文与 TxChartTooltip 定位。默认tooltip以悬停的数据点（日期或类目）为标题，数据行写所属系列名与数值；数据项本身就是系列时（环图、仪表、图例聚焦）两者相同，只保留数据行。dot、line、dashed 保留不同标记结构。绘图区支持方向键、Home/End、Enter/空格和Escape；图例与周期使用原生按钮。

CSS 变量

组件读取现有 --tx-chart-categorical-1、--tx-chart-grid-line 及TuffEx文字、表面和线条token。--tx-dither-pad、--tx-dither-gap 调整组件间距。Canvas颜色在数据/主题变化时解析，不在每帧读取；SVG定义使用实例稳定的Vue useId()。

技术实现

来源等价与运行时保护

固定提交为 43c29ce9cdd16459e3eab4992381b8d35b38776a。已读取 src/components/dither-charts、src/components/simple-comp 两目录，包括非目录图形及pattern、图例、tooltip辅助源码。以下11对同字节：ChartCard、DitherBarChart、DitherBook、DitherChartsGrid、DitherHeatmapGrid、DitherRadialChart、DitherScatterChart、DitherSparklineMatrix、MembersGrowthChart、PaymentsChart、SimpleCompExtracted。

另外11对没有按同名静默合并。它们的可见几何公式相同，但 dither-charts 给全部11项添加缓存的 ResizeObserver 尺寸与可见性/减少动态效果保护；活动、设备、漏斗、收入、半圆仪表、存储、气泡、在线图还限制DPR≤2，而环图、堆叠、增长在两个副本中已经限制DPR。漏斗、存储、在线图额外限制30fps。差异通过 DITHER_SOURCE_DIFFERENCES 与演示逐项记录。两来源共用受保护的运行方式，不重新引入每帧布局读取、隐藏后台循环或违背用户偏好的动效。

Canvas后备尺寸响应resize与DPR变化。数据插值使用公共spring，几何未变化时缓存路径，颜色与布局读取不进入逐帧循环；失活和卸载释放计时器、监听器、observer与RAF。SSR以及SVG纹理选择也能显示真实SVG几何。不引入React、Motion、Recharts或ECharts渲染器。

组合与归属

DitherChartsGrid 对应可遍历的演示目录。独立 Book、DitherBook 归 TxFlipBook，不是图表别名。演示通过真实flip-book与 plan-card、payments、members-growth API组合原提取页面；页内容使用调用方自制图形，不分发上游第三方照片。