Editor 참조

product="editor"는 Kaleidr의 지도 편집 도구를 웹페이지에 마운트합니다. 편집기는 마운트 대상 내부에 자체 지도를 만들고 그 위에 패널을 표시합니다. iframe이 아니라 페이지 문서 안에서 실행됩니다.

임베디드 편집기는 수정 내용을 페이지 메모리에만 보관합니다. 임베디드 버전에서는 저장, 내보내기, 게시가 불가능하며 변경 콜백도 없습니다. 페이지를 새로고침하거나 handle.destroy()를 호출하면 수정 내용이 사라집니다.

항목	내용
키	게시 가능한 키(`kld_pk_live_…`). 필수입니다.
범위	`design`. 새 키에 기본으로 포함됩니다.
요금제	Free를 포함한 모든 요금제.
렌더링 위치	웹페이지 내부.
영구 저장	지원하지 않습니다.
인스턴스	페이지당 하나.
CSP	Content Security Policy의 Editor 항목을 참조하세요.

단계별 설명은 Editor 연결을 참조하세요.

기능 범위

포함	포함되지 않음
지도 위에 배치하는 텍스트	데이터 탭과 데이터 세트 업로드
지도 위에 배치하는 이미지	Studio의 샘플 지도와 스타일 유형 디자인 카탈로그
마커	AI 패널
팝업	3D 모델 라이브러리
배경: 지도 뒤의 배경	공유 및 게시
레이어: 바탕 지도의 라벨, 3D 건물, 조명 및 지형	프로젝트: 지도 저장, 열기 및 목록 보기
디자인: 바탕 지도 피처, 카테고리 또는 지역을 선택해 스타일 변경	로그인
범례: 라벨과 범례 설정

왼쪽 열은 Editor의 도구 패널 순서를 나타냅니다. 임베디드 Editor의 디자인은 스타일 변경 도구이며 Studio의 디자인 카탈로그는 포함하지 않습니다.

마운트

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072],
  zoom: 12,
});

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night" center="-0.1276,51.5072" zoom="12"
             style="display:block; height:640px"></kaleidr-map>

마운트 대상에는 높이가 있어야 합니다. Editor는 대상 너비와 높이를 100% 사용합니다. 대상 안의 기존 요소를 제거하지 않고 새 요소를 추가하므로 빈 컨테이너를 사용하세요.

옵션

마운트 옵션	속성	유형	기본값	필수	설명
`product`	`product`	`'editor'`	없음	예	Editor를 선택합니다.
`publishableKey`	`publishable-key`	문자열	없음	예	`design` 범위를 가진 `kld_pk_…` 키입니다. 서버 키 `kld_sk_…`는 브라우저에서 요청 전에 거부됩니다.
`styleId`	`style-id`	문자열	조직의 기본 바탕 지도, 없으면 `kaleidr-morning`	아니요	`kaleidr-night` 같은 스타일 ID 또는 전체 스타일 URL입니다. 스타일 ID를 참조하세요. 마운트 시 고정됩니다.
`center`	`center`	`[longitude, latitude]`; 속성은 `"longitude,latitude"`	`[0, 0]`	아니요	시작 중심점입니다.
`zoom`	`zoom`	숫자	`2`	아니요	시작 확대 수준입니다. `center` 없이도 적용됩니다.
`pitch`	`pitch`	숫자, 도	`0`	아니요	시작 기울기입니다.
`bearing`	`bearing`	숫자, 도	`0`	아니요	시작 회전입니다.
`theme`	`theme`	객체 또는 객체를 나타내는 JSON 문자열	없음	아니요	이름이 정해진 키 최대 17개입니다. 테마 키를 참조하세요. 마운트 시 한 번만 읽습니다.
`apiBase`	`api-base`	URL	`https://api.kaleidr.com/inference-api`	아니요	세션 교환 요청 주소입니다. `/inference-api` 경로가 필요합니다. 운영 환경에서는 설정할 필요가 없습니다.
`tileBase`	`tile-base`	URL	`https://tile.kaleidr.com`	아니요	스타일 ID를 조회할 호스트입니다. 운영 환경에서는 설정할 필요가 없습니다.
`base`	`base`	URL	`https://cdn.kaleidr.com`	아니요	SDK가 `editor.js`를 로드할 출처입니다. 출처만 사용하며 기본 주소 재정의에 있는 출처만 허용됩니다.
`enabled`	`flag`	불리언	없음	아니요	활성화 제어의 마운트별 설정입니다.

shareId, map, mapTarget, contained, viewerBase는 Editor 마운트에 아무 영향이 없습니다. styleUrl 옵션은 없으며 URL을 styleId로 전달하면 됩니다.

바탕 지도

Editor는 다음 순서로 바탕 지도를 선택합니다:

지정한 styleId.
설정되어 있다면 조직의 기본 바탕 지도.
kaleidr-morning.

마운트 후 바탕 지도를 변경할 수 없으며 Editor에서는 handle.setStyle을 지원하지 않습니다. 변경하려면 편집기를 파괴하고 다시 마운트해야 하며, 이때 수정 내용은 사라집니다.

카메라

center에는 경도를 먼저 입력합니다.
각 값은 숫자 또는 숫자 문자열일 수 있습니다.
유한한 숫자가 아닌 마운트 옵션은 무시되고 기본값이 적용됩니다. 콘솔에는 예를 들어 [kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.가 표시됩니다.
요소의 카메라 속성이 숫자가 아니라면 메시지 없이 무시하고 기본값을 사용합니다.

테마 키

theme은 아래 목록의 키로 구성된 객체입니다. 각 값은 CSS 값을 담은 문자열이어야 합니다. 목록에 없는 키 또는 비어 있지 않은 문자열이 아닌 값은 알림 없이 무시됩니다. fontSizeBase: 14는 효과가 없고 fontSizeBase: '14px'는 작동합니다.

키	스타일 대상	예제
`brandColor`	기본 버튼, 포커스 테두리, 활성 도구.	`'#0b5fff'`
`brandColorHover`	`brandColor`의 호버 상태.	`'#0847c2'`
`brandColorOn`	`brandColor` 위에 놓인 글자와 아이콘.	`'#ffffff'`
`textColor`	본문과 제목.	`'#111827'`
`textColorMuted`	캡션 같은 보조 텍스트.	`'#6b7280'`
`surfaceColor`	카드와 대화 상자의 배경색.	`'#ffffff'`
`borderColor`	테두리와 구분선.	`'#e5e7eb'`
`glassBg`	반투명 패널 배경: 사이드바와 확장 패널. 단색을 사용하면 평면적인 느낌을 줍니다.	`'rgba(255,255,255,0.8)'`
`glassBlur`	해당 패널의 `backdrop-filter`.	`'blur(12px)'`
`cardRadius`	카드와 대화 상자 모서리 둥글기.	`'12px'`
`buttonRadius`	버튼과 칩의 모서리 둥글기.	`'8px'`
`listRadius`	목록 행의 모서리 둥글기.	`'6px'`
`fontPrimary`	기본 `font-family`.	`'"Inter", system-ui, sans-serif'`
`fontMono`	고정폭 `font-family`.	`'ui-monospace, monospace'`
`fontSizeBase`	기본 글꼴 크기.	`'14px'`
`sidebarRailWidth`	사이드바 도구 레일 너비.	`'64px'`
`quickActionsWidth`	떠 있는 빠른 동작 도구 모음 너비.	`'320px'`

Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    buttonRadius: '8px',
  },
});

동작 방식:

테마에 임의의 CSS 사용자 지정 속성을 넣을 수는 없습니다. '--my-color' 같은 키는 무시됩니다.
Editor가 마운트된 동안 값이 문서 루트 요소에 적용되므로 대화 상자가 어느 위치에 표시되든 같은 값을 사용할 수 있습니다. Editor가 파괴되면 이전 값이 복원됩니다.
테마는 마운트할 때 한 번만 읽습니다. Editor는 handle.setTheme을 지원하지 않으며 마운트 후 theme 속성을 변경하면 경고만 기록됩니다.
문자열로 지정한 theme은 {로 시작하는 JSON이어야 합니다. 그 외의 값은 콘솔 경고와 함께 무시됩니다.

제어 핸들

Kaleidr.mount는 핸들을 동기적으로 반환합니다. 각 제품에 대한 핸들 매트릭스를 참조하세요.

멤버	Editor에서의 동작
`handle.product`	`'editor'`
`handle.setCamera(camera)`	Editor 지도를 이동합니다.
`handle.setTheme(theme)`	미지원. 경고를 기록하고 아무것도 하지 않습니다.
`handle.setStyle(style)`	미지원. 경고를 기록하고 아무것도 하지 않습니다.
`handle.destroy()`	편집기와 지도를 제거하고 테마 값을 복원하며 세션 갱신을 중지합니다. 수정 내용도 사라집니다.

핸들에는 map 멤버가 없습니다. 페이지에서 Editor 내부의 지도 객체에 접근할 수 없습니다.

`setCamera(camera)`

handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });

필드	유형	설명
`center`	`[number, number]`	경도, 위도.
`zoom`	숫자	확대 수준.
`pitch`	숫자	기울기(도).
`bearing`	숫자	회전(도).
`duration`	숫자	애니메이션 시간(밀리초). 생략하거나 `0`이면 애니메이션 없이 이동합니다.

편집기가 아직 로드 중일 때 발생한 호출은 대기열에 저장되었다가 시작 후 실행됩니다.

마운트 후 요소 속성

마운트된 <kaleidr-map product="editor">에서 center, zoom, pitch, bearing를 변경하면 애니메이션 없이 지도가 이동합니다. style-id, theme 또는 다른 속성 변경은 영향을 주지 않습니다.

수명 주기

이벤트	결과
`Kaleidr.mount(...)` 또는 요소 연결	세션 교환과 `editor.js` 로드가 동시에 실행되고 모두 완료되면 편집기가 시작됩니다.
`handle.destroy()` 또는 요소 제거	편집기와 수정 사항이 제거됩니다.
요소를 다른 부모 요소로 이동	기존 마운트를 파괴하고 다시 마운트합니다. 수정 내용이 사라집니다.
편집기가 있는데 두 번째 편집기를 마운트	지원하지 않습니다. 먼저 첫 번째를 파괴하세요.
페이지 새로고침	수정 사항이 사라집니다.

페이지에서 실행되는 요소

iframe 제품과 달리 Editor는 이를 포함하는 페이지에 영향을 줍니다:

https://cdn.kaleidr.com에서 수 MB 크기의 editor.js 번들을 로드합니다.
JavaScript로 문서에 스타일시트를 추가합니다.
https://tile.kaleidr.com에서 바탕 지도의 스타일, 타일, 스프라이트, 폰트를 요청합니다. 스타일, 스프라이트, 폰트 요청은 게시 가능한 키를 key 쿼리 매개변수로 보내서 바탕 지도 호스트가 페이지를 인식하도록 합니다. 타일 데이터 요청에는 키가 없습니다. 세션 토큰을 URL에 넣지 않습니다.
지도용 blob: URL에서 웹 워커를 시작합니다.
마운트 동안 문서 루트 요소에 테마 값을 설정합니다.

관련 CSP 지침은 Content Security Policy에 있습니다.

콘솔 메시지

메시지	의미
`[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	키를 전달하지 않았습니다. 아무것도 표시되지 않습니다.
`[kaleidr:editor] kaleidr session exchange failed (<status>)`	세션 교환이 거부되었습니다. 이유는 Network 탭의 응답에서 볼 수 있습니다. 403은 `detail`에 코드가 있으며, 예를 들어 `design`이 없는 경우 `insufficient_scope`입니다. 429는 `error`에 코드가 있습니다.
`…/sdk/sessions` CORS 오류 후 `[kaleidr:editor]` fetch 오류	키가 없거나 취소되었거나 페이지 출처가 허용되지 않았습니다.
`[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. …`	서버 키를 전달했습니다. 요청은 보내지 않습니다.
`[kaleidr:editor] ignored <field>: <value> is not a finite value — using <default> instead.`	`Kaleidr.mount`에 전달된 카메라 옵션이 숫자가 아니었습니다. 요소 속성에서는 이 메시지가 나오지 않습니다.
`[kaleidr:editor] <message>`	Editor 지도가 스타일 또는 타일 로드 실패 등의 오류를 보고했습니다.
`[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.`	`theme` 문자열이 JSON 객체가 아닙니다.
`[kaleidr] theme JSON parse failed (…); ignored.`	`theme`에 올바르지 않은 JSON이 있습니다.
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op. …`	`setTheme`을 호출했거나 마운트 후 `theme` 속성이 바뀌었습니다.
`[kaleidr] setStyle() is not supported on product "editor" — the call is a no-op. …`	`setStyle`을 호출했습니다.

제공하지 않는 기능

수정 내용을 저장, 내보내기, 게시하기.
변경 이벤트, 준비 완료 이벤트, 오류 콜백.
지도 객체, 사용자 지정 레이어, 사용자가 그린 내용 읽기.
마운트 후 바탕 지도나 테마 변경.
한 페이지에 둘 이상의 Editor.

기능 범위​

마운트​

옵션​

바탕 지도​

카메라​

테마 키​

제어 핸들​

setCamera(camera)​

마운트 후 요소 속성​

수명 주기​

페이지에서 실행되는 요소​

콘솔 메시지​

제공하지 않는 기능​

관련 문서​