live2d-web
日本語
English한국어日本語
DocumentationJavaScript

JavaScript

React に依存しない基本 API を使います。

作成・読み込み・破棄

JavaScript API は1つの Canvas を管理します。モデルを操作する前に読み込みの完了を待ち、画面から外すときは必ず dispose() を呼んでください。

ts
import { createLive2D } from 'live2d-web'
 
const character = await createLive2D({
  container: document.querySelector('#avatar'),
  coreUrl: '/live2dcubismcore.min.js',
  src: '/models/model.model3.json',
})
 
await character.motion('TapBody', 0)
 
// When the host view is removed:
character.dispose()

モデルを複数置く

addModel() は同じキャンバスにもう一つモデルを読み込みます。2体目のキャラクターが 2つ目の WebGL コンテキストではなくモデル1つで済みます。ブラウザーはコンテキスト数に 上限があります。

two.ts
const stage = await createLive2D({
  container: document.querySelector('#stage')!,
  coreUrl: '/live2dcubismcore.min.js',
  src: '/models/host.model3.json',
})
 
const guest = await stage.addModel({
  src: '/models/guest.model3.json',
  fit: { scale: 0.8, offsetX: 0.3, units: 'stage' },
})
 
await guest.motion('Tap', 0)
guest.dispose()

追加した順に描画されるので、あとから足したモデルが上に来ます。モデルごとに fit、 モーション、表情、パラメーター、ヒットエリアを持ち、1つを破棄してもキャンバスと 残りはそのままです。src は任意で、省くと空のキャンバスから始めて addModel() で 埋められます。

インスタンスの motion() や fit などはそのまま残り、src で作ったモデルを 指します。配置オーバーレイは一度に1つのモデルだけが持ちます。

Canvas のアクセシビリティ

Canvas を支援技術に公開する必要がある場合だけ意味を指定します。オプションを 省略すると、従来のマークアップを維持します。

ts
const character = await createLive2D({
  accessibility: {
    label: '動く案内キャラクター',
    fallbackText: '案内キャラクターのイラスト',
  },
  container: document.querySelector('#avatar'),
  src: '/models/model.model3.json',
})

情報を伝えないモデルには { mode: 'decorative' } を使います。タップや モーションはキーボードで操作できる通常の DOM ボタンやコントロールでも提供してください。 ランタイムは Canvas に tabIndex や role="application" を自動追加しません。

画面のライフサイクルに合わせる

インスタンスはコンテナーを所有する画面で保持します。非表示タブで描画が不要なら一時停止し、画面を外すときに破棄します。dispose() は複数回呼んでも安全です。

ts
const onVisibility = () => document.hidden ? character.pause() : character.resume()
document.addEventListener('visibilitychange', onVisibility)
window.addEventListener('pagehide', () => {
  document.removeEventListener('visibilitychange', onVisibility)
  character.dispose()
}, { once: true })

Vue、Svelte、その他のフレームワーク

専用のエントリーがあるのは React だけです。コンポーネントツリーには、ライフサイクルフックには不要な手当てが要るからです。React は Strict Mode で effect を2回実行し、並行してレンダリングし、後始末の時期を自分で決めます。ほかのフレームワークでは、命令型 API がそのままバインディングになります。マウント時にインスタンスを作り、アンマウント時に破棄し、その間はフレームワークが呼ぶところのローカルな状態に持たせてください。

Vue
<script setup lang="ts">
import { createLive2D } from 'live2d-web'
import { onBeforeUnmount, onMounted, ref } from 'vue'
 
const host = ref<HTMLElement>()
let character: Awaited<ReturnType<typeof createLive2D>> | undefined
 
onMounted(async () => {
  character = await createLive2D({
    container: host.value!,
    coreUrl: '/live2dcubismcore.min.js',
    src: '/models/model.model3.json',
  })
})
 
onBeforeUnmount(() => character?.dispose())
</script>
 
<template>
  <div ref="host" />
</template>

Vue Vite の例に一式があります。Svelte や Solid もライフサイクルの名前が違うだけで、形は同じです。

通常の DOM で操作と再試行を用意

モーション、表情、再試行は Canvas 外のボタンで提供します。準備前は無効にし、失敗時は Live2DError.code を表示して、Core、アセット、WebGL の原因を修正してから再作成します。