vue-data-ui-skilld

graphieros/vue-data-ui [email protected]

• 文档：https://vue-data-ui.graphieros.com/（各组件页面：`https://vue-data-ui.graphieros.com/docs#vue-ui-`）
• 仓库：https://github.com/graphieros/vue-data-ui
• 需要 vue >= 3.3.0；jspdf >= 3.0.1 是可选的对等依赖，仅在使用 PDF 导出功能时安装（package.json:112-119）。
• 类型随包提供；主入口类型解析到 dist/types/vue-data-ui.d.ts（package.json:66-90）。

参考资料

• API 一览：入口、导入方式、工具函数、组合式函数、SSR。
• 组件：组件目录、常用 props/emits/公开方法/插槽。
• 自定义：配置模式、主题、用户选项、插槽、无障碍、响应式、大数据。
• 从 v3.19.2 迁移到 v3.25.9：API 变更，包括 v3.25.0 的破坏性变更。

设置

npm i vue-data-ui

<script setup>
import { ref } from "vue";
import { VueUiDonut } from "vue-data-ui";
import "vue-data-ui/style.css"; // required css

const dataset = ref([
  { name: "A", value: 12 },
  { name: "B", value: 88 },
]);
const config = ref({ theme: "zen" });
</script>

<template>
  <VueUiDonut :dataset="dataset" :config="config" />
</template>

每个组件都接受 dataset prop 和 config 对象 prop。传入部分 config，组件会将其与默认值合并。建议使用 computed 配置，以确保修改保持响应式。

常见任务

基于默认值构建类型安全的配置并安全地覆盖：

import { getVueDataUiConfig, mergeConfigs, type VueUiXyConfig } from "vue-data-ui";

const config = computed<VueUiXyConfig>(() => mergeConfigs({
  defaultConfig: getVueDataUiConfig("vue_ui_xy"), // snake_case component key
  userConfig: { chart: { title: { text: "Sales" } } },
}));

通过模板 ref 调用公开方法（各组件提供的方法有所不同，参见组件参考）：

const chart = useTemplateRef("chart");
const data = await chart.value.getData();
const img = await chart.value.getImage({ scale: 2 }); // { imgUri, base64, title, width, height, aspectRatio }
chart.value.showSeries("Series 1"); // or hideSeries("Series 1")

使用 tooltip.customFormat: ({ seriesIndex, datapoint, series, config }) => string 自定义工具提示，或通过 #tooltip-before / #tooltip-after 插槽提供更丰富的内容。使用 formatter: ({ value, config }) => string 自定义数据标签。

从 v3.22.0 起，可使用 useTooltipPosition 组合式函数将工具提示移出指针所在位置：

import { useTooltipPosition } from "vue-data-ui/composables";
const chartRef = useTemplateRef("chartRef");
const tooltipPosition = useTooltipPosition(chartRef); // ComputedRef<"left" | "right" | "center">
const config = computed(() => ({ chart: { tooltip: { position: tooltipPosition.value } } }));

在服务端渲染静态 SVG（无需浏览器）：

import { createStaticVueUiXy } from "vue-data-ui/ssr"; // or 'vue-data-ui/ssr/vue-ui-xy' (treeshaken)
const svg = await createStaticVueUiXy({ dataset, config });

最佳实践

• 对于超大型数据集，使用 VueUiXyCanvas 代替 VueUiXy；调整 config.downsample.threshold（LTTB 降采样）。默认值：Xy 为 1095，XyCanvas 为 10000，Quadrant/Scatter/Sparkline/SparkTrend 为 1095（README.md:979-1002）。
• 使用 config.responsive: true 时，将图表放在尺寸固定的容器中；容器高度设为 100% 会导致图表无限增高（README.md:968-977）。
• 如需启用指针光标，请设置 config.useCursorPointer: true；默认禁用，以满足无障碍需求（README.md:1521-1529）。
• 要启用无障碍替代文本按钮，请设置 userOptions.buttons.altCopy: true，并提供 userOptions.callbacks.altCopy 回调（README.md:1488-1519）。
• 使用专用的 reverse 配置标志反转坐标轴（自 v3.20.7 起），不要通过负值来变通。X 轴：chart.grid.labels.xAxis.reverse；Y 轴：chart.grid.labels.yAxis.reverse（VueUiXy）。
• 通过开发环境变量控制 config.debug 和 config.devHints.enable；某些重要警告仍会输出（v3.23.0、v3.23.2 发行说明）。
• 使用 legend.selectAllToggle.show: true 提供全选复选框（系列数量超过 2 时）；该选项切换时也会触发 @selectLegend（自 v3.19.9 起）。
• 对于主入口未重新导出的工具函数（例如 adaptColorToBackground），请从 vue-data-ui/utils 导入（参见 dist/utils.js 导出列表）。
• 不要在 VueUiXy 中混用 bar 类型系列和连续型 { x, y } 系列，否则柱形会被隐藏并记录警告（v3.20.7 发行说明）。
• #tooltip 插槽会替换默认内容；#tooltip-before / #tooltip-after 插槽则会分别在内容前面添加或后面追加内容。

版本限制和破坏性变更

• v3.25.0（破坏性变更）：showOnlyAtModulo 现在会使用真正的取模运算，且 modulo 的默认值从 12 改为 2；使用新增的 showFirstAndLast: true 强制显示首尾标签。影响 VueUiXy（含 SSR）、VueUiStackbar、VueUiStackline、VueUiCandlestick。参见迁移指南。
• v3 相比 v2 没有破坏性变更，但部分 padding 配置有所变化（README.md:185-200）。
• 自 v3.14.3 起，语言环境文件已移除；时间标签依赖 Intl（v3.14.3 发行说明）。