React

React가 필요한 컴포넌트에서만 연동 모듈을 불러옵니다.

컴포넌트 붙이기

Live2DCanvas는 Canvas 렌더링을 관리하고, Live2DModel은 모델을 불러오며 컴포넌트가 제거될 때 자원을 정리합니다.

tsx

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

모델을 여럿 두기

Canvas 하나에 모델을 원하는 만큼 둘 수 있습니다. WebGL 컨텍스트를 함께 쓰므로 두 번째 캐릭터가 브라우저가 허용하는 몇 안 되는 컨텍스트를 하나 더 쓰지 않습니다.

Duo.tsx

<Live2DCanvas coreUrl="/live2dcubismcore.min.js">
  <Live2DModel src="/models/host.model3.json" fit="full" />
  <Live2DModel
    src="/models/guest.model3.json"
    fit={{ scale: 0.8, offsetX: 0.3, units: 'stage' }}
  />
</Live2DCanvas>

쓴 순서대로 그려지므로 뒤에 온 모델이 위에 옵니다. 모델마다 자기 fit, followPointer, onTap을 갖고, <LipSync>나 트래킹 자식은 자기가 속한 모델에 붙습니다. 하나를 unmount해도 Canvas와 나머지는 그대로입니다.

paused는 Canvas의 것입니다. <Live2DCanvas paused>가 전체를 멈춥니다. 모델에 쓰던 것도 그대로 동작하며, 모델 중 하나라도 paused면 Canvas가 멈춥니다.

Canvas 접근성

의미 있는 캐릭터는 이미지로 설명하고, 장식뿐인 Canvas는 보조 기술에서 숨기세요. 라이브러리는 Canvas를 자동으로 키보드 포커스 대상으로 만들지 않습니다. 탭·모션 기능은 일반 DOM 버튼으로도 제공하고 prefers-reduced-motion 환경에서는 버튼이 만드는 애니메이션을 줄이세요.

tsx

<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()로 controller를 가져오고 사용자 이벤트에서 명령을 호출하세요. 모델 준비 전에는 null이며 unmount 후에는 기존 controller를 다시 사용할 수 없습니다.

tsx

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이 자원을 소유하게 두세요. 모델을 교체할 때는 모델 식별자를 key로 사용합니다.