configure-scales-guides-color

Configure Scales, Guides, and Color

本技能讲述如何配置 TanStack Charts 的比例尺、参考线、坐标轴、边距、图例、分组与颜色，同时不接管响应式范围的所有权。建议按 trigger → inspect → decide → build → verify 的顺序工作。应用拥有语义域（semantic domains）与颜色策略；TanStack Charts 拥有推断域、响应式位置范围、参考线测量和最终绘制解析。

设置

对推断域使用 factories，对固定语义域使用已配置实例：

import { colorLegend, defineChart, lineY } from '@tanstack/charts'
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { scaleOrdinal } from '@tanstack/charts/scales/ordinal'
import { scalePoint } from '@tanstack/charts/scales/point'

const rows = [
  { week: 'May 4', package: 'core', downloads: 820 },
  { week: 'May 11', package: 'core', downloads: 960 },
  { week: 'May 4', package: 'react', downloads: 610 },
  { week: 'May 11', package: 'react', downloads: 730 },
]

const color = scaleOrdinal<string, string>()
  .domain(['core', 'react'])
  .range(['#2563eb', '#f97316'])

export const chart = defineChart({
  marks: [lineY(rows, { x: 'week', y: 'downloads', z: 'package' })],
  scales: {
    x: { scale: () => scalePoint().padding(0.2) },
    y: {
      scale: scaleLinear,
      nice: true,
      grid: true,
      axis: { label: 'Downloads' },
    },
  },
  color: { scale: color, legend: colorLegend({ label: 'Package' }) },
})

核心模式

按语义选择比例尺

数值位置 → 紧凑的 scaleLinear。
有宽度的类别 → 紧凑的 scaleBand。
无宽度的类别 → 紧凑的 scalePoint。
稳定的类别颜色 → 紧凑的 scaleOrdinal。
经过时间、非线性变换、径向映射、统计分箱或连续颜色 → 精确的 d3-scale 系列。

在配置 D3 实例之前，请阅读所有权矩阵（references/scale-guide-ownership.md）。

有意共享域

import { scaleLinear } from '@tanstack/charts/scales/linear'

export const percentScale = scaleLinear().domain([0, 1])

export const sharedPercentAxis = {
  scale: percentScale,
  axis: {
    label: 'Conversion rate',
    ticks: { format: (value: number) => `${Math.round(value * 100)}%` },
  },
}

已配置的实例会在筛选、分面或关联视图中保持域稳定。Charts 会复制它并分配当前范围。

将系列标识与绘制保持分离

import { lineY } from '@tanstack/charts'

const rows = [
  { date: '2026-08-01', series: 'api', status: 'healthy', value: 91 },
  { date: '2026-08-01', series: 'worker', status: 'healthy', value: 84 },
]

export const mark = lineY(rows, {
  x: 'date',
  y: 'value',
  z: 'series',
  color: 'status',
})

使用 z 表示几何分组，使用 color 表示语义比例尺值，使用 fill/stroke 表示最终的局部绘制覆盖。

将刻度候选值与标签碰撞分离

刻度数量、间距或值决定候选值。标签抽稀、旋转、格式化与优先级决定哪些候选标签保持可读。自动边距容纳参考线；它们并不能让每个标签都清晰可读。

常见错误

关键：分配位置像素范围

错误：

x: {
  scale: scaleLinear().range([0, 640])
}

正确：

x: {
  scale: scaleLinear
}

最终的绘图范围会在容器测量与参考线边距解析后发生变化。

来源：API-FRICTION.md F-002；docs/concepts/scales-and-d3.md

关键：使用默认实例进行推断

错误：

y: {
  scale: scaleLinear()
}

正确：

y: {
  scale: scaleLinear
}

比例尺实例拥有其域；factory 将域推断委托给图表通道。

来源：CHANGELOG.md 0.0.1 迁移；docs/concepts/scales-and-d3.md

高：意外地将颜色用作几何标识

错误：

lineY(rows, { x: 'date', y: 'value', color: 'status' })

正确：

lineY(rows, {
  x: 'date',
  y: 'value',
  z: 'series',
  color: 'status',
})

当 z 缺失时，离散颜色通道也可能分割相连的几何图形。

来源：API-FRICTION.md F-009, F-013；docs/concepts/data-and-channels.md

高：将包含关系当作碰撞规避

错误：依赖自动边距来解决密集刻度标签。

正确：定义候选间距、抽稀优先级、旋转、缩写，或不同的响应式组合方式。

边距将参考线保持在表面内；它们不保证标签彼此避让。

来源：API-FRICTION.md F-023, F-160；docs/guides/responsive-charts.md

高：张力——响应式适配与比较稳定性

在窄宽度下减少标签或改变组合方式，但不要为了适配图表而静默改变共享域、阈值或类别颜色分配。

另见：design-responsive-charts/SKILL.md § 常见错误

参考

比例尺、参考线、分组与颜色的所有权。

另见：design-responsive-charts/SKILL.md 与 debug-and-verify-charts/SKILL.md——最终范围取决于布局，空白图表往往暴露比例尺契约失败。