compose-marks-and-views

用途

本技能用于将语义编码（semantic encodings）翻译为 TanStack Charts 中的标记（marks）、图层（layers）、注释（annotations）、分面（facets）与协调视图（coordinated views）。其核心观点是：一个图表类型通常不是按名称查找到的组件，而是多个共享刻度的标记的组合。文档建议采用「trigger → inspect → decide → build → verify」的工作流程。

主要能力与核心模式

图层顺序

先铺设宽泛的上下文，最后绘制直接证据。声明顺序即为绘制顺序，每个标记可以使用不同的数据（datum）类型。示例代码中依次使用 areaY、ruleY、lineY、dot、text 五种标记构建图表：

import { areaY, defineChart, dot, lineY, ruleY, text } from '@tanstack/charts'
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { scalePoint } from '@tanstack/charts/scales/point'

const rows = [
  { month: 'Jan', low: 72, value: 80, high: 89, label: '' },
  { month: 'Feb', low: 77, value: 86, high: 96, label: '' },
  { month: 'Mar', low: 84, value: 94, high: 106, label: 'Launch' },
]

export const chart = defineChart({
  marks: [
    areaY(rows, { id: 'range', x: 'month', y1: 'low', y2: 'high' }),
    ruleY([90], { id: 'target' }),
    lineY(rows, { id: 'trend', x: 'month', y: 'value' }),
    dot(
      rows.filter((row) => row.label),
      { id: 'events', x: 'month', y: 'value' },
    ),
    text(
      rows.filter((row) => row.label),
      {
        id: 'event-labels',
        x: 'month',
        y: 'value',
        text: 'label',
        dy: -10,
      },
    ),
  ],
  scales: {
    x: { scale: scalePoint },
    y: { scale: scaleLinear },
  },
})

让一个图层独占交互所有权

使用 decorative 包裹支撑性标记，保留几何形状与刻度物化，但移除重复的焦点、提示框与激活点：

import { defineChart, dot, lineY } from '@tanstack/charts'
import { decorative } from '@tanstack/charts/mark/decorative'

const rows = [
  { id: 'jan', month: 'Jan', value: 80 },
  { id: 'feb', month: 'Feb', value: 86 },
]

export const chart = defineChart({
  marks: [
    decorative(lineY(rows, { x: 'month', y: 'value' })),
    dot(rows, { x: 'month', y: 'value', key: 'id' }),
  ],
})

使用显式几何分组

当几何标识与绘制语义不一致时，将几何标识（z）与绘制语义（color）分开：

import { lineY } from '@tanstack/charts'

const rows = [
  { date: '2026-08-01', region: 'North', value: 42, status: 'healthy' },
  { date: '2026-08-01', region: 'South', value: 37, status: 'healthy' },
]

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

选择最小的完整组合

按以下顺序逐级升级：

一个内置或一方提供的复合标记。
多个共享刻度的内置标记。
分面或命名视图。
传给内置标记的 D3 预处理行数据。
由普通标记构建的 compositeMark。
发出渲染器中立场景节点的自定义标记。
应用自有的覆盖层或手势控制器。

文档建议在创建自定义标记前先阅读标记选择矩阵。

分面用于重复问题，视图用于不同角色

当每个面板对某个分组提出相同问题时使用 facetChart；当需要焦点与上下文、边缘汇总或角色不同的面板时使用 composeViews。语义共享状态应保留在应用中，不要通过 DOM 节点同步视图。

常见错误

严重：把图表编码为一条自定义路径。错误做法是发出包含完整可视化的一条路径；正确做法是保留标记局部的数据、通道、刻度与交互点，只扩展内置标记无法表达的几何。单一整体路径会丢弃自动域、类型化行、可移植渲染、焦点所有权与可组合性。
中等：期望面积图自己画出线。错误做法是只写 areaY；正确做法是同时写 areaY 与 lineY，因为面积与线是独立图层，各自拥有独立的样式、状态与点所有权。
高：让装饰性图层拥有重复的点。错误做法是让线、面积、点和标签层层叠加在同一行数据上且每个标记都可交互；正确做法是选定语义所有者，并用 decorative 包裹始终绘制的支撑性标记。重复点会造成重复的键盘停顿、焦点候选与提示框行。
高：在用户代码中重建已支持的坐标。错误做法是在图表布局前把极坐标、空间、层级或网络几何投影为任意像素；正确做法是使用一方提供的坐标／布局原语，或当确实需要最终边界时使用已解析布局的标记。用户侧投影会隐藏响应式最终边界工作并重复能力模块。

限制与说明

资料中未提供该技能的收费、价格、平台支持范围或具体使用效果等信息。相关参考来源包括 docs/concepts/grammar-of-graphics.md、docs/guides/custom-marks-and-renderers.md、docs/reference/marks/line-and-area.md、API-FRICTION.md、docs/guides/tooltips-and-focus.md、docs/examples/index.md，并建议参考 build-chart-interactions/SKILL.md 与 extend-tanstack-charts/SKILL.md。