live2d-web 문서

JavaScript

React에 의존하지 않는 기본 API를 사용합니다.

생성·로드·정리

JavaScript API는 하나의 Canvas와 모델을 관리합니다. 모델을 조작하기 전에 로드가 끝날 때까지 기다리고, 화면에서 제거할 때는 반드시 dispose()를 호출하세요.

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()

Canvas 접근성

Canvas를 보조 기술에 노출해야 할 때만 의미를 지정하세요. 옵션을 생략하면 기존 마크업을 그대로 유지합니다.

const character = await createLive2D({
  accessibility: {
    label: '움직이는 안내 캐릭터',
    fallbackText: '안내 캐릭터 그림',
  },
  container: document.querySelector('#avatar'),
  src: '/models/model.model3.json',
})

정보를 전달하지 않는 모델에는 { mode: 'decorative' }를 사용하세요. 탭과 모션 동작은 키보드로 조작할 수 있는 일반 DOM 버튼이나 컨트롤로도 제공해야 합니다. 런타임은 Canvas에 tabIndex나 role="application"을 자동 추가하지 않습니다.

화면 생명주기와 맞추기

인스턴스는 컨테이너를 소유한 화면에서 보관하세요. 숨겨진 탭에서 애니메이션이 필요 없다면 일시 정지하고, 화면이 사라질 때 정리합니다. dispose()는 여러 번 호출해도 안전합니다.

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

조작과 재시도 UI 만들기

모션, 표정, 재시도는 Canvas 밖의 일반 버튼으로 제공하세요. 로드 전에는 비활성화하고, 실패하면 Live2DError.code를 표시합니다. Core 경로, 모델 자산, WebGL 환경을 수정한 뒤 새 인스턴스로 재시도하세요.