live2d-web ドキュメント

React

必要なコンポーネントでのみ React 連携を読み込みます。

Client Component で使う

/react は Client Component でのみ読み込んでください。Live2DCanvas が描画を管理し、Live2DModel がモデルの読み込みと画面から外れたときの破棄を行います。

'use client'
 
import { Live2DCanvas, Live2DModel } from 'live2d-web/react'
 
export function Avatar() {
  return (
    <Live2DCanvas coreUrl="/live2dcubismcore.min.js">
      <Live2DModel src="/models/model.model3.json" />
    </Live2DCanvas>
  )
}

Canvas のアクセシビリティ

意味のあるキャラクターは画像として説明し、装飾だけの Canvas は支援技術から隠します。ライブラリは Canvas を自動的にキーボードフォーカスの対象にしません。タップやモーションには通常の DOM ボタンも用意し、 prefers-reduced-motion ではアニメーションを抑えてください。

<Live2DCanvas
  accessibility={{
    label: '動く案内キャラクター',
    describedBy: 'avatar-help',
  }}
  coreUrl="/live2dcubismcore.min.js"
>
  <Live2DModel src="/models/model.model3.json" />
</Live2DCanvas>
 
<p id="avatar-help">下のモーションボタンに反応するキャラクターです。</p>
<button type="button" onClick={() => controller?.motion('TapBody', 0)}>
  あいさつを再生
</button>

情報を伝えない Canvas には accessibility={{ mode: 'decorative' }} を使います。

準備後の controller を使う

モデル配下のコンポーネントで useLive2DModel() を呼び、ユーザー操作からコマンドを実行します。準備前は null で、unmount 後の controller は再利用できません。

import { useLive2DModel } from 'live2d-web/react'
 
function MotionButton() {
  const controller = useLive2DModel()
  return <button disabled={!controller} onClick={() => controller?.motion('TapBody', 0)}>あいさつを再生</button>
}
 
<Live2DModel src="/models/model.model3.json"><MotionButton /></Live2DModel>

Strict Mode と再試行

開発時の React Strict Mode では mount と cleanup が繰り返されます。controller をグローバルに保存せず、Live2DCanvas と Live2DModel にリソースを所有させてください。モデル変更時はモデル ID を key に使います。