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／公開メソッド／スロット。
• カスタマイズ：設定パターン、テーマ、ユーザーオプション、スロット、a11y、レスポンシブ、大規模データ。
• v3.19.2 から v3.25.9 への移行：v3.25.0 の破壊的変更を含む API の差分。

セットアップ

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 を通じて公開メソッドを呼び出します（コンポーネントごとに利用可能です。components リファレンスを参照してください）。

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 });

ベストプラクティス

• 非常に大きなデータセットには VueUiXy の代わりに VueUiXyCanvas を使用し、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 でポインターカーソルを有効にできます。a11y のため、デフォルトでは無効です（README.md:1521-1529）。
• userOptions.buttons.altCopy: true と userOptions.callbacks.altCopy コールバックを設定して、a11y の代替テキストボタンを有効にします（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 を適用するようになり、modulo のデフォルト値は 12 から 2 に変更されました。端のラベルを必ず表示するには、新しい showFirstAndLast: true を使用してください。VueUiXy（+SSR）、VueUiStackbar、VueUiStackline、VueUiCandlestick に影響します。移行ガイドを参照してください。
• v3 は v2 との間に破壊的変更はありませんが、一部の padding 設定が変更されています（README.md:185-200）。
• v3.14.3 以降、ロケールファイルは削除されています。時間ラベルは Intl に依存します（v3.14.3 リリースノート）。