unovis-vue-skilld

@unovis/vue 1.7.0

Unovis 是一个模块化的数据可视化框架。@unovis/vue 为 @unovis/ts（README.md）中的核心类提供自动生成的 Vue 3 封装组件。

版本和环境

• 软件包：@unovis/[email protected]。
• 对等依赖：@unovis/ts 必须固定为 1.7.0，vue 版本为 ^3（package.json:56-59）。安装两者时版本必须完全一致：npm install -P @unovis/ts @unovis/vue（README.md:16）。两个软件包版本不一致会导致对等依赖解析失败。
• 优先使用 ESM。软件包设有 type: module、./* 子路径导出和 sideEffects: false（package.json:28-39）。
• 无需导入 CSS。样式会在运行时通过 JS 注入（index.js:1）。
• 文档：https://unovis.dev/docs/intro。组件文档位于 https://unovis.dev/docs/components/<Name>。示例库：https://unovis.dev/gallery。

封装组件的工作方式

每个 Vis* 组件都是一个 @unovis/ts 类的轻量封装。编写代码前请确认以下规则：

• Props 与核心配置接口一一对应，例如 AreaConfigInterface。在脚本中使用 camelCase，在模板中使用 kebab-case：:line-width="2"、:stack-min-height="true"。
• 访问器是函数。将其作为 props 传入：:x="d => d.x"、:y="['sales', 'cost'].map(k => d => d[k])"。
• data 可以设在容器或组件上。容器会将其 data 共享给所有子组件。只有当容器没有 data 时，子组件才会回退到自己的 data（components/area/index.js:35）。对于包含多个组件的图表，请在容器层级传入数据。
• 响应性：配置变更会调用核心类的 setConfig，然后调用 render。data 变更会调用 setData。两者都会就地更新图表，不会重新挂载。
• 每个封装组件都通过 defineExpose 暴露 component，这是一个指向核心 @unovis/ts 实例的 ref。使用模板 ref 调用核心方法：chart.value?.component?.destroy()。
• 每个模块还会导出选择器，例如 VisAxisSelectors 等于 @unovis/ts 中的 Axis.selectors。通过 events prop 和 tooltip 的 triggers 使用选择器（事件和工具提示）。
• 容器通过 provide 和 inject 收集子组件。将 Vis* 子组件放入容器的默认插槽中。XY 容器会等到至少一个子组件注册后才创建图表（containers/xy-container/index.js:50-52），因此 v-for 和条件子组件都可以正常使用。
• 图例和地图是独立组件。VisBulletLegend、VisFlowLegend、VisRollingPinLegend、VisLeafletMap 和 VisLeafletFlowMap 会渲染到各自的 DOM 节点中。请在容器外使用它们。其他所有组件都需要容器上下文。

快速入门

<script setup lang="ts">
import { ref } from 'vue'
import { VisXYContainer, VisLine, VisAxis } from '@unovis/vue'

type DataRecord = { x: number; y: number }
const data = ref<DataRecord[]>([
  { x: 0, y: 0 },
  { x: 1, y: 2 },
  { x: 2, y: 1 },
])
const x = (d: DataRecord) => d.x
const y = (d: DataRecord) => d.y
</script>

<template>
  <VisXYContainer :data="data" :height="300">
    <VisLine :x="x" :y="y" />
    <VisAxis type="x" />
    <VisAxis type="y" />
  </VisXYContainer>
</template>

尺寸：容器宽度会适应其父级。请显式设置 height，否则默认值为 300px（XY 容器文档）。

组件目录

两种容器：用于带坐标轴 XY 图表的 VisXYContainer，以及用于单个独立可视化并可选配工具提示的 VisSingleContainer。完整列表及关键 props：components.md。

• XY 组件：VisArea、VisLine、VisScatter、VisStackedBar、VisGroupedBar、VisBoxplot（1.7 新增）、VisTimeline、VisXYLabels。
• 辅助组件：VisAxis、VisCrosshair、VisTooltip、VisBrush、VisFreeBrush、VisPlotband、VisPlotline、VisAnnotations。
• 单容器组件：VisDonut、VisNestedDonut、VisRadialBar（1.7 新增）、VisHeatmap（1.7 新增）、VisTreemap、VisSankey、VisChordDiagram、VisGraph、VisTopoJSONMap。
• 独立组件：VisBulletLegend、VisFlowLegend、VisRollingPinLegend、VisLeafletMap、VisLeafletFlowMap。

常见任务

序数 x 值

让 x 访问器返回索引。再将坐标轴刻度格式化为标签。

<script setup lang="ts">
const x = (d: DataRecord, i: number) => i
const tickFormat = (i: number) => data.value[i]?.category ?? ''
</script>

<template>
  <VisXYContainer :data="data">
    <VisStackedBar :x="x" :y="d => d.value" />
    <VisAxis type="x" :tick-format="tickFormat" />
  </VisXYContainer>
</template>

带十字准线的工具提示

<script setup lang="ts">
import { VisStackedBarSelectors } from '@unovis/vue'
const triggers = {
  [VisStackedBarSelectors.bar]: (d: DataRecord) => `${d.category}: ${d.value}`,
}
</script>

<template>
  <VisXYContainer :data="data">
    <VisStackedBar :x="x" :y="d => d.value" />
    <VisCrosshair :template="triggers" />
    <VisAxis type="x" />
  </VisXYContainer>
</template>

更多用法模式，包括吸附模式和事件，请参阅：events-tooltips.md。

使用 svgDefs 自定义填充

<script setup lang="ts">
const gradientDef = `
  <linearGradient id="area-gradient" x1="0" y1="0" x2="0" y2="1">
    <stop offset="0%" stop-color="#4d8cfd" stop-opacity="0.8" />
    <stop offset="100%" stop-color="#4d8cfd" stop-opacity="0.1" />
  </linearGradient>`
</script>

<template>
  <VisXYContainer :data="data" :svg-defs="gradientDef">
    <VisArea :x="x" :y="y" color="url(#area-gradient)" />
  </VisXYContainer>
</template>

使用基线访问器绘制瀑布图

VisStackedBar 在 1.7 中新增了 baseline，用于绘制浮动柱（components/stacked-bar/index.js:11）。将它与 barStyle 搭配使用，可显示虚线预测值（components/stacked-bar/index.js:10）。

<script setup lang="ts">
// data records carry the floating bar start and end
const baseline = (d: WaterfallRecord) => d.start
const y = (d: WaterfallRecord) => d.end - d.start
const color = (d: WaterfallRecord) => (d.delta >= 0 ? '#00c19a' : '#ff6b7e')
</script>

<template>
  <VisXYContainer :data="data">
    <VisStackedBar :x="x" :y="y" :baseline="baseline" :color="color" />
    <VisAxis type="x" />
    <VisAxis type="y" />
  </VisXYContainer>
</template>

使用 bleed 对齐堆叠图表

bleed 会覆盖容器为边缘标记预留的空间。它可以接受一个 Spacing 对象或函数。通过 onRenderComplete 获取标记最大的图表的水平 bleed，然后将其传给其他图表（containers/xy-container/index.js:29-30）。指南：https://unovis.dev/docs/guides/bleed。

<script setup lang="ts">
import { ref } from 'vue'
const horizontalBleed = ref<{ left?: number; right?: number }>()
const onRenderComplete = (svg: SVGSVGElement, margin: unknown, bleed: { left: number; right: number }) => {
  horizontalBleed.value = { left: bleed.left, right: bleed.right }
}
</script>

<template>
  <VisXYContainer :data="data" :on-render-complete="onRenderComplete">
    <VisScatter :x="x" :y="y" :size="25" />
  </VisXYContainer>
  <VisXYContainer :data="data" :bleed="horizontalBleed">
    <VisLine :x="x" :y="y" />
  </VisXYContainer>
</template>

颜色和图案

1.7 新增了图表级颜色同步和图案填充：

• VisXYContainer、VisSingleContainer 和 VisBulletLegend 上的 colorFunction 可将键映射为颜色（containers/xy-container/index.js:39、html-components/bullet-legend/index.js:17）。
• 组件上的 colorKeys 用于命名与其 y 访问器对应的稳定键（components/area/index.js:25）。
• VisArea、VisLine、VisScatter、VisGroupedBar、VisStackedBar、VisDonut 等组件上的 pattern 可添加条纹、圆点和斜线图案。

详情和示例：color-patterns.md。

注意事项

• 将 @unovis/ts 和 @unovis/vue 固定为完全相同的版本。peer 版本范围为 1.7.0，且不带插入符号（package.json:57）。
• VisCrosshair、VisTimeline 和 VisBoxplot 仅将 data 声明为 Vue 属性。其他所有配置都会作为属性传递。如果这些组件上的配置属性似乎未生效，请升级到 1.7.0：它们的 data 属性在 1.6.5 到 1.7 之间曾被静默丢弃（修复 PR）。
• 轴标签在顶部或底部被裁切？增大容器的 margin，例如 :margin="{ top: 10, right: 10, bottom: 10, left: 10 }"。
• Nuxt 和 SSR：自 1.6.4 起，核心已支持 SSR。如果出现 hydration 或 document 错误，请将图表包在 <ClientOnly> 中（issue 607）。如需在 Node 20+ 中进行无头渲染，请使用独立的 @unovis/ssr 包（https://unovis.dev/releases/1.7）。
• 严格 CSP：在导入库之前设置 window.UNOVIS_NONCE。指南：https://unovis.dev/docs/guides/csp。
• 深色主题：为 body 添加 theme-dark 类。按组件覆盖 --vis-dark-* 变量（主题指南）。

参考资料

• components.md：完整的导出目录，包含容器规则和关键属性。
• events-tooltips.md：事件、选择器、工具提示、十字准线、注释。
• color-patterns.md：颜色同步、图案、CSS 变量、主题。
• migration-v1.7.md：从 1.6.x 到 1.7.0 的变更中会影响 Vue 代码的部分。