live2d-web 문서

React

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

Client Component에서 사용하기

live2d-web/react는 Client Component에서만 불러오세요. Live2DCanvas는 Canvas 렌더링을 관리하고, 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()로 controller를 가져오고 사용자 이벤트에서 명령을 호출하세요. 모델 준비 전에는 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이 자원을 소유하게 두세요. 모델을 교체할 때는 모델 식별자를 key로 사용합니다.