unovis-vue-skilld

@unovis/vue 1.7.0

Unovis はモジュール式のデータ可視化フレームワークです。@unovis/vue は、@unovis/ts のコアクラス用に自動生成された Vue 3 ラッパーを提供します（README.md）。

バージョンと環境

• パッケージ：@unovis/[email protected]。
• ピア依存関係：@unovis/ts は正確に 1.7.0 に固定され、vue は ^3 です（package.json:56-59）。両方をまったく同じバージョンでインストールしてください：npm install -P @unovis/ts @unovis/vue（README.md:16）。2 つのパッケージのバージョンが一致しないと、ピア依存関係の解決に失敗します。
• 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* コンポーネントは、1 つの @unovis/ts クラスを包む薄いラッパーです。コードを書く前に、次のルールを確認してください。

• Props はコア設定インターフェースに 1 対 1 で対応します。たとえば 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 を通じて、コア @unovis/ts インスタンスへの参照である component を公開します。テンプレート ref を使ってコアメソッドを呼び出します：chart.value?.component?.destroy()。
• 各モジュールはセレクターもエクスポートします。たとえば VisAxisSelectors は @unovis/ts の Axis.selectors と同じです。セレクターは events prop やツールチップの triggers と併用してください（イベントとツールチップ）。
• コンテナーは provide と inject を使って子を収集します。Vis* の子はコンテナーのデフォルトスロットに配置してください。XY コンテナーは少なくとも 1 つの子が登録されるまでチャートの作成を保留するため（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 コンテナーのドキュメント）。

コンポーネント一覧

コンテナーは 2 種類あります。軸付き 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>

ベースラインアクセサーを使ったウォーターフォールチャート

浮動バー用の baseline が 1.7 で VisStackedBar に追加されました（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 は、コンテナーが端のマーク用に確保するスペースを上書きします。Spacing オブジェクトまたは関数を指定できます。最大のマークを持つチャートの水平ブリードを onRenderComplete で取得し、ほかのチャートに渡します（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 は、同じバージョンに固定してください。ピア依存関係の範囲はキャレットのない 1.7.0 です（package.json:57）。
• VisCrosshair、VisTimeline、VisBoxplot で Vue のプロパティとして宣言されているのは data のみです。その他の設定はすべて属性として渡されます。この 3 つで設定プロパティが無視されるように見える場合は、1.7.0 にアップグレードしてください。1.6.5 から 1.7 への移行時に、data プロパティが暗黙のうちに破棄されていました（修正 PR）。
• 軸ラベルが上端または下端で切れる場合は、コンテナーの margin を増やしてください。例：:margin="{ top: 10, right: 10, bottom: 10, left: 10 }"。
• Nuxt と SSR：コアは 1.6.4 以降、SSR に対応しています。ハイドレーションや 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：Vue コードに影響する、1.6.x から 1.7.0 への変更点です。