React API

React 환경에서 사용하는 VRISM 뷰어 SDK API입니다.

VrismViewer 컴포넌트

기본 뷰어 컴포넌트입니다.

import { VrismViewer } from '@vrism/viewer-sdk'

<VrismViewer
  token: string
  contentId: string
  camera?: CameraConfig
  ui?: UIConfig
  isMobileView?: boolean
  className?: string
  style?: React.CSSProperties
  
  // 이벤트 핸들러
  onChange?: () => void
  onLoadScene?: () => void
  onLoadUpdate?: (percentage?: number) => void
  onLoadFinish?: () => void
  onStepChange?: (options: { direction?: 'prev' | 'next', step?: number }) => void
  onError?: (error: any) => void
  onFullscreenChange?: (isFullscreen: boolean) => void
/>

Props

필수 Props

token: string - 인증 토큰
contentId: string - 로드할 콘텐츠 ID

설정 Props

camera?: CameraConfig - 카메라 설정
ui?: UIConfig - UI 설정
isMobileView?: boolean - 모바일 뷰 모드

스타일링 Props

className?: string - CSS 클래스명
style?: React.CSSProperties - 인라인 스타일

이벤트 Props

onLoadFinish?: () => void

로딩 진행률이 100%에 도달했을 때 호출
⚠️ 주의: 아직 3D 장면이 준비되지 않을 수 있음

onLoadScene?: () => void

3D 장면이 완전히 준비되어 사용자 조작이 가능할 때 호출
뷰어가 실제로 준비된 시점
✅ 권장: 뷰어 제어 API 호출은 이 콜백에서 수행하세요.

💡 차이점: onLoadFinish는 로딩 UI만 완료, onLoadScene은 실제 상호작용 가능한 상태입니다.

onStepChange?: (options: StepChangeOptions) => void

스텝이 변경되었을 때 호출

onChange?: () => void

뷰어 상태가 변경되었을 때 호출

onLoadUpdate?: (percentage?: number) => void

로딩 진행률 업데이트 시 호출

onError?: (error: any) => void

에러 발생 시 호출

onFullscreenChange?: (isFullscreen: boolean) => void

전체화면 모드 변경 시 호출

기본 사용 예시

import { VrismViewer } from '@vrism/viewer-sdk'

function App() {
  return (
    <VrismViewer
      token="your-token-here"
      contentId="your-content-id"
      ui={{
        viewerBackgroundColor: '#ffffff',
        gestureGuide: true,
        fullscreenButton: true
      }}
      camera={{
        autoRotation: -2,
        controls: {
          enableZoom: true,
          enablePan: true,
          enableRotate: true
        }
      }}
      // 뷰어 제어는 onLoadScene에서 안전하게 실행
      onLoadScene={() => {
        console.log('뷰어 사용 준비 완료 - API 호출 가능');
      }}
      onLoadFinish={() => {
        console.log('로딩 바 100% 완료');
      }}
      onError={(error) => console.error('에러:', error)}
    />
  )
}

Ref 메서드

React 컴포넌트는 ref를 통해 다음 메서드들을 제공합니다:

import { useRef } from 'react'
import { VrismViewer, VrismViewerRef } from '@vrism/viewer-sdk'

function App() {
  const viewerRef = useRef<VrismViewerRef>(null)

  const handleClick = async () => {
    // 설정 조회
    const config = viewerRef.current?.getConfig()
    console.log('현재 설정:', config)
    
    // 카메라 위치 조회
    const position = viewerRef.current?.getCameraPosition()
    console.log('카메라 위치:', position)
    
    // 뷰어 제어 (동기 메서드)
    viewerRef.current?.setGestureGuideShow(false)
    viewerRef.current?.setFullscreenOpen(true)
    viewerRef.current?.setStep(2)
    viewerRef.current?.onVTOClick()
    
    // 3D 위치 선택 (비동기)
    const clickedPos = await viewerRef.current?.getClickedPosition()
    if (clickedPos) {
      console.log('선택된 위치:', clickedPos)
    }
    
    // 뷰어 리로드 (비동기)
    await viewerRef.current?.reload({
      ui: { viewerBackgroundColor: '#000000' }
    })
  }

  return (
    <VrismViewer
      ref={viewerRef}
      token="your-token-here"
      contentId="your-content-id"
    />
  )
}

Ref 메서드 목록

`getConfig(): object`

현재 뷰어 내부 상태를 반환합니다. (동적값)

const config = viewerRef.current?.getConfig()
// { angleX: 0.5, angleY: 1.2, zoom: 1.8, ... }

`getCameraPosition(): object`

현재 카메라 위치와 타겟 위치를 반환합니다.

const position = viewerRef.current?.getCameraPosition()
console.log('카메라 위치:', position.cameraPosition)  // {x, y, z}
console.log('타겟 위치:', position.targetPosition)   // {x, y, z}

반환값:

{
  cameraPosition: {x: number, y: number, z: number},
  targetPosition: {x: number, y: number, z: number}
}

`setGestureGuideShow(show?: boolean): void`

제스처 가이드 표시를 제어합니다.

// 제스처 가이드 숨기기
viewerRef.current?.setGestureGuideShow(false)
// 제스처 가이드 표시
viewerRef.current?.setGestureGuideShow(true)

`setFullscreenOpen(open?: boolean): void`

전체화면 모드를 제어합니다.

// 전체화면 열기
viewerRef.current?.setFullscreenOpen(true)
// 전체화면 닫기
viewerRef.current?.setFullscreenOpen(false)

`setStep(step: number): void`

스텝을 설정합니다.

// 2번째 스텝으로 이동
viewerRef.current?.setStep(2)

`onVTOClick(): void`

VTO 기능을 트리거합니다.

viewerRef.current?.onVTOClick()

`getClickedPosition(): Promise<PickedPositionData | null>`

3D 위치 선택 API를 실행합니다.

⚠️ 중요: 이 메서드는 step 기능이 활성화되고 step 항목이 1개 이상 설정된 상태에서만 정상적으로 동작합니다. ui.step.enabled: true와 ui.step.items 배열을 설정하세요.

// step 기능 활성화 및 항목 설정 필요
<VrismViewer
  ref={viewerRef}
  token="your-token-here"
  contentId="your-content-id"
  ui={{
    step: {
      enabled: true,  // 필수 설정
      items: [        // 1개 이상 필수
        {
          id: 1,
          name: '전체 보기',
          order: 1,
          anchor: {
            desktop: {
              position: { x: 0, y: 0, z: 5 },
              target: { x: 0, y: 0, z: 0 }
            }
          }
        }
      ]
    }
  }}
/>

// 메서드 사용
const position = await viewerRef.current?.getClickedPosition();
if (position) {
  console.log('선택된 위치:', position.anchor.position);
}

`reload(config?: ViewerConfig): Promise<void>`

뷰어를 리로드합니다.

`destroy(): void`

뷰어 리소스를 정리합니다.

고급 사용 예시

상세 설정이 포함된 예시

import { VrismViewer } from '@vrism/viewer-sdk'

function App() {
  return (
    <VrismViewer
      token="your-token-here"
      contentId="your-content-id"
      camera={{
        autoRotation: -2,
        desktop: {
          angle: { x: 0.2, y: 0.1 },
          zoom: 1.5,
          limits: {
            angleUp: 1.5,
            angleDown: -1.5,
            zoomMin: 0.5,
            zoomMax: 3.0
          }
        },
        mobile: {
          angle: { x: 0.3, y: 0.2 },
          zoom: 2.0
        },
        controls: {
          enableZoom: true,
          enablePan: true,
          enableRotate: true
        }
      }}
      ui={{
        viewerBackgroundColor: '#f8f9fa',
        gestureGuide: {
          enabled: true,
          imageUrl: '/custom-gesture-guide.png'
        },
        userGuide: true,
        fullscreenButton: true,
        vtoControl: false,
        loader: {
          enabled: true,
          type: 'circle',
          size: 'medium',
          loaderFillColor: '#007bff',
          loaderPlaceholderColor: '#e9ecef'
        },
        step: {
          enabled: true,
          stepControls: true,
          stepDots: true,
          stepAnnotation: true
        }
      }}
      isMobileView={false}
      className="my-viewer"
      style={{ width: '100%', height: '500px' }}
      onLoadScene={() => console.log('뷰어 준비 완료')}
      onStepChange={(options) => console.log('스텝 변경:', options)}
      onError={(error) => console.error('에러:', error)}
      onFullscreenChange={(isFullscreen) => console.log('전체화면:', isFullscreen)}
    />
  )
}

참고: UI 설정에서 각 요소들을 비활성화(false)하면 해당 UI가 표시되지 않습니다.

React 전용 타입 정의

VrismViewerRef

interface VrismViewerRef {
  getConfig: () => {
    angleX?: number
    angleY?: number
    zoom?: number
    panX?: number
    panY?: number
    panZ?: number
    angleLimitUp?: number
    angleLimitDown?: number
    zoomLimitMin?: number
    zoomLimitMax?: number
    angleXMobile?: number
    angleYMobile?: number
    zoomMobile?: number
    panXMobile?: number
    panYMobile?: number
    panZMobile?: number
    angleLimitUpMobile?: number
    angleLimitDownMobile?: number
    zoomLimitMinMobile?: number
    zoomLimitMaxMobile?: number
  }
  getCameraPosition: () => {
    cameraPosition: {x: number, y: number, z: number}
    targetPosition: {x: number, y: number, z: number}
  }
  setGestureGuideShow: (show?: boolean) => void
  setFullscreenOpen: (open?: boolean) => void
  setStep: (step: number) => void
  onVTOClick: () => void
  destroy: () => void
  reload: (config?: ViewerConfig) => Promise<void>
  getClickedPosition: () => Promise<PickedPositionData | null>
}

VrismViewerProps

interface VrismViewerProps {
  token: string
  contentId: string
  camera?: CameraConfig
  ui?: UIConfig
  isMobileView?: boolean
  className?: string
  style?: React.CSSProperties
  onChange?: () => void
  onLoadScene?: () => void
  onLoadUpdate?: (percentage?: number) => void
  onLoadFinish?: () => void
  onStepChange?: (options: { direction?: 'prev' | 'next'; step?: number }) => void
  onError?: (error: any) => void
  onFullscreenChange?: (isFullscreen: boolean) => void
}

import type { VrismViewerProps } from '@vrism/viewer-sdk'

const viewerProps: VrismViewerProps = {
  token: 'your-token',
  contentId: 'your-content-id'
}

공통 타입들

공통으로 사용되는 ViewerConfig, CameraConfig, UIConfig, Position, PickedPositionData, StepItem 등의 타입은 공통 타입 정의를 참조하세요.

React API#

VrismViewer 컴포넌트#

Props#

필수 Props#

설정 Props#

스타일링 Props#

이벤트 Props#

기본 사용 예시#

Ref 메서드#

Ref 메서드 목록#

getConfig(): object#

getCameraPosition(): object#

setGestureGuideShow(show?: boolean): void#

setFullscreenOpen(open?: boolean): void#

setStep(step: number): void#

onVTOClick(): void#

getClickedPosition(): Promise<PickedPositionData | null>#

reload(config?: ViewerConfig): Promise<void>#

destroy(): void#

고급 사용 예시#

상세 설정이 포함된 예시#

React 전용 타입 정의#

VrismViewerRef#

VrismViewerProps#

공통 타입들#