Embedding Guide

노트

헤더 · 사이드바가 있는 웹 화면 안에 VIZWide3D 뷰어를 넣는 방법입니다. (3.0 기준)

먼저 이것만

1. 뷰어 루트(.VIZWeb_Main)에는 아래 CSS 하나만 줍니다.
2. 뷰어를 넣을 영역에 높이를 줍니다.
3. 콘솔에 [VIZWide3D] 경고가 나오면 경고에 붙은 링크를 따라 아래 표에서 조치를 찾습니다.

.VIZWeb_Main { position: relative; width: 100%; height: 100%; }

경고

루트에 position: absolute; left: 0; top: 0 을 주지 마세요. 오류 없이 모델 트리 · 검색 패널이 사이드바 뒤에 숨습니다.

올바른 배치 (position: relative)	잘못된 배치 (position: absolute; left: 0; top: 0)
모델 트리가 뷰어 영역 안에 열립니다.	뷰어가 페이지 전체를 덮고, 모델 트리는 사이드바 뒤(빨간 점선)에 열립니다.

---

1. 레이아웃 안에 넣기

body 바로 아래가 아니어도 됩니다. 레이아웃 영역 안에 넣는 것이 정상적인 사용법입니다.

<style>
  html, body { height: 100%; margin: 0; }
  body { display: flex; flex-direction: column; }
  .row { flex: 1; display: flex; min-height: 0; }
  aside { width: 320px; }
  #viewerArea { flex: 1; min-width: 0; }
  .VIZWeb_Main { position: relative; width: 100%; height: 100%; }
</style>

<header>…</header>
<div class="row">
  <aside>…</aside>
  <div id="viewerArea"></div>
</div>

<script type="module">
  import VIZCore3DModule from "./VIZCore3D/VIZCore3D.js";

  const main = document.createElement('div');
  main.className = 'VIZWeb_Main';
  const view = document.createElement('div');
  view.className = 'VIZCore3D';
  main.appendChild(view);
  document.getElementById('viewerArea').appendChild(main);

  const vizcore = new VIZCore3DModule(view);
  vizcore.Init({
    event: {
      onConfiguration: () => { vizcore.Configuration.Type = vizcore.Enum.UI_TYPE.RIBBONBAR; },
      onInit: () => { /* 모델 열기 */ },
    },
  });
</script>

• Configuration.Type 을 지정해야 리본 · 패널이 나옵니다. 지정하지 않으면 3D 화면만 나옵니다.
• 영역 크기가 바뀌어도(스플리터, 사이드바 접기) 뷰어가 알아서 맞춥니다.

2. Vue · React 에서 쓰기

• 컴포넌트 루트를 div.VIZWeb_Main 으로 두고, 안쪽 뷰 요소를 ref 로 넘깁니다.
• 언마운트할 때 vizcore.Release() 를 부릅니다. 뷰어가 만든 화면과 이벤트가 모두 정리됩니다.
• React 는 effect 의 cleanup 에서 Release() 를 부르면 StrictMode 에서도 문제없습니다.

전체 코드는 Getting Started 3.0 의 Vue · React 탭에 있습니다.

3. 패널을 코드로 열기

툴바 버튼과 같은 동작입니다.

vizcore.Tree.Show(true);           // 모델 트리 열기 (성공하면 true)
vizcore.ModelSearch.Show(true);    // 검색 열기
vizcore.Tree.Show(false);          // 닫기

vizcore.UIElement.DockPanel.SetDockSize('left', 320);   // 왼쪽 패널 폭
vizcore.UIElement.OnPanelShown((id) => console.log('열림', id));

4. 콘솔 경고와 조치

화면 배치에 문제가 있으면 콘솔에 한 번 경고합니다.

경고 끝의 링크를 누르면 아래 표의 해당 행으로 이동합니다.

경고 코드	뜻	조치
container-zero	뷰어 크기가 0	뷰어를 넣은 영역에 높이를 주세요. 탭 전환 등으로 일부러 숨긴 상태면 무시해도 됩니다.
root-escaped	루트가 페이지 전체 기준으로 놓임	루트 CSS 를 position: relative 로 바꾸세요. 패널이 사이드바 뒤에 숨는 원인입니다.
root-outside-parent	루트가 영역 밖으로 나감	루트의 크기 · 여백을 확인하세요.
root-offscreen	루트가 화면 밖에 있음	루트의 위치 지정을 확인하세요.
root-detached	루트가 페이지에 붙어 있지 않음	뷰어를 만들기 전에 루트를 페이지에 붙이세요.
duplicate-id	페이지에 뷰어 내부와 같은 id 가 있음	페이지 쪽 id 를 바꾸세요. 뷰어 내부 id 는 모두 sh- 로 시작합니다.
panel-covered	패널이 다른 요소에 가려짐	대개 root-escaped 와 같은 원인입니다. 루트 CSS 를 확인하세요.
panel-zero · panel-outside · panel-offscreen	패널 크기가 0 이거나 영역 · 화면 밖	container-zero 와 같이 영역 높이와 루트 CSS 를 확인하세요.

5. 페이지 CSS 와의 관계

• 뷰어 CSS 는 뷰어 안에만 적용됩니다.
• 페이지의 .active, .hidden, #workspace 같은 규칙은 뷰어에 영향을 주지 않습니다.
• button { … }, * { … } 처럼 태그 전체에 거는 규칙은 뷰어 안에도 적용됩니다. 범위를 좁혀 주세요.

6. 점검표

• 콘솔에 [VIZWide3D] 경고가 없다
• 툴바의 Model Tree · Search · Property Tree 가 뷰어 영역 안에 열린다
• 사이드바 폭을 바꾸거나 접어도 3D 화면이 따라온다