커스텀 위젯 만들기
커스텀 위젯은 HTML/CSS/JavaScript 코드로 UI를 만들고, 설정 패널을 구성하여 코드 수정 없이 설정값을 변경할 수 있도록 하는 구조예요. 이 도움말에서는 커스텀 위젯 만드는 방법을 알아보실 수 있습니다. 커스텀 위젯 스튜디오에 대해 궁금하다면 이 가이드를 읽어 주세요.
목차
📢 안내 | 최신 프롬프트 및 코드 제한 가이드는 별도 문서에서 관리하고 있어요. 아래 링크를 참고해 주세요!
프롬프트 및 코드 가이드 업데이트 바로가기 →1. 커스텀 위젯 UI 코드 만들기
위젯 소스 에디터에서 HTML, CSS, JavaScript 탭에 Handlebars 문법을 활용하여 코드를 작성합니다.
1-1. 코드 기본 정책
- 위젯 하나의 코드는 HTML, CSS, Javascript 각각 1만 자까지 작성할 수 있어요. (총 3만자)
- 커스텀 위젯은 12컬럼 100% width가 기본 레이아웃이에요.
- 기본적으로 모든 위젯은 그리드 시스템에 따라 모바일 반응형으로 만들어져요. viewport 기준으로 CSS 미디어쿼리를 활용하여 모바일 반응형을 더 쉽게 제작할 수 있고, 의도한 대로 디자인을 구현할 수 있어요.💡 참고: 커스텀 위젯은 모바일 전용 섹션에는 삽입할 수 없어요. 미디어쿼리를 활용하여 하나의 위젯에서 PC와 모바일 디자인을 모두 처리하는 것을 권장합니다.
- 공통 디자인 설정값 중 폰트를 제외한 나머지 설정값들은 자동 반영되지 않아요. 커스텀 위젯은 기본적으로 아임웹의 전역 스타일이 초기화된 상태에서 동작해요. 단, 커스텀 위젯의 css 코드에서 font family 를 선언하지 않을 경우, 폰트는 공통 디자인 설정의 폰트를 따라가요.
- 웹폰트를 사용할 수 있어요. 기존처럼 SEO > body code 에 웹폰트 링크를 넣은 다음, 커스텀 위젯의 CSS 코드에서 font family를 선언하는 방식으로 사용하면 돼요. 단, 폰트 적용 상태는 미리보기로만 확인할 수 있어요.
- 위젯 소스 코드를 수정하면 해당 위젯이 연동된 모든 사이트에서 즉시 업데이트 돼요.단, 게시하기까지 완료해야 실제 방문자가 보는 사이트에 업데이트됩니다. 현재 버전 관리 기능은 제공되지 않으며, 수정은 최대 100회까지 가능합니다. 수정한 코드를 저장한 후에는 이전 버전으로 되돌릴 수 없으니 주의해 주세요. 단, 소스 코드를 수정하더라도 변수명(스키마)이 동일하면 기존에 설정한 값은 그대로 유지돼요.
- 예를 들어 기존 위젯에
{{backgroundColor}}변수가 있고, 수정 후에도 동일한{{backgroundColor}}변수가 있으면 이전에 설정한 값이 유지됩니다.
- 예를 들어 기존 위젯에
1-2. 커스텀 위젯 지원 불가 내역
아래의 항목들은 현재(2026.05.01) 커스텀 위젯 스튜디오에서 지원하지 않는 기능이에요. 단, 서비스가 고도화 되면서 해당 내용은 변경될 수 있어요.
- 아임웹 내부 데이터(회원 정보, 상품 정보 등) 연동
- 아임웹 쇼핑 기능(장바구니, 결제 등) 연동
- 외부 네트워크 요청 (fetch, XMLHttpRequest 등)
- 외부 라이브러리(CDN) 연동
- 위젯 간 데이터 공유 또는 통신 코드 위젯에서 하던 것처럼 다른 위젯의 ID를 호출하여 제어하는 방식은 사용할 수 없어요. 다른 코드 위젯에서 커스텀 위젯의 ID를 호출하여 제어하는 것도 불가능해요.
- 쿠키 또는 로컬스토리지 연동
- iframe 삽입
1-3. 코드 오류 지원 범위 및 사용 제한
- 아임웹은 회원이 직접 작성한 코드의 오류, 버그, 의도한 대로 동작하지 않는 문제에 대한 디버깅 또는 수정 등을 도와드리기 어렵습니다. 코드 관련 문제는 작성하신 코드를 직접 점검하시거나, 웹 개발 전문가의 도움을 받아 해결하시길 권장드려요.
- 단, 아임웹 플랫폼 자체의 오류(에디터 미리보기가 뜨지 않는 경우, 연동 기능 자체가 동작하지 않는 경우 등)는 고객센터로 문의해 주시면 확인해 드립니다.
- 아임웹 이용약관 제5장 서비스 이용 제한 내 제15조 1항에 근거하여, 회원이 만든 커스텀 위젯 코드가 아임웹 서비스의 정상적인 운영을 방해할 경우 해당 커스텀 위젯의 사용을 제한할 수 있습니다.
2. 설정패널 만들기
설정 패널의 기본 원리는 다음과 같아요.
2-1. 설정패널 제작 방법
방법 1: 코드 주석으로 자동 생성
Handlebars 주석 형태의 annotation을 코드에 작성하면, 에디터가 이를 파싱하여 설정 패널을 자동으로 생성해요.
@name에 작성한 이름이 변수명이 되며, 바로 아랫줄의 이중 중괄호로 코드에서 해당 값을 참조합니다. 속성 선언과 변수 참조가 코드 한 곳에서 동시에 이루어져요.
지원 태그
| 태그 | 필수 | 설명 |
|---|---|---|
@name | 필수 | 대상 변수명 |
@type | 선택 | 패널 타입 (9종, 2-2 항목 참조) |
@default | 선택 | 기본값 |
@label | 선택 | 패널 항목 라벨 |
@placeholder | 선택 | 입력 필드 플레이스홀더 |
@values | 선택 | select / segment 옵션 값 (쉼표 구분) |
@valueNames | 선택 | select / segment 옵션 라벨 (@values와 함께 사용) |
방법 2: 패널 만들기에서 항목 추가
설정 패널 화면에서 추가 버튼을 클릭하여 설정 항목의 컴포넌트 유형을 선택·추가하는 방식이에요.
- [패널 만들기] 화면에서 [추가] 버튼을 클릭하여 설정 항목의 컴포넌트 유형을 선택·추가해 주세요
- 속성의 유형(type), 변수 이름(id), 설정 패널에서 노출될 항목의 제목(label) 등을 폼에서 입력해 주세요
- 변수 이름을 위젯 인터페이스 코드(HTML·CSS·JavaScript)에
{{변수명}}형태로 직접 입력하여, 속성과 코드 변수를 연결해 주세요
이로써 설정 패널 항목과 코드 변수의 연결이 완성돼요. 이후 사용자가 설정 패널에서 값을 변경하면, 연결된 변수를 통해 위젯 화면에 즉시 반영돼요.
2-2. 설정패널 지원 컴포넌트 타입
설정 패널에서 지원하는 컴포넌트 타입은 다음과 같아요. 모든 컴포넌트의 필수 속성은 변수 id와 라벨명입니다.
| 항목명 | 정의 | 특징 |
|---|---|---|
| outlined-textfield (입력창) | 텍스트, 정수, 실수 데이터를 입력할 수 있는 입력창 | 최대 100자까지 입력 가능하며, 데이터 유형(텍스트/정수/실수) 선택이 필수입니다. 디폴트 값, 최대값, 최소값, 단위(최대 5글자), 플레이스홀더(최대 10글자)를 선택적으로 설정할 수 있어요. |
| text-editor (에디터) | 줄글 텍스트를 입력할 수 있는 에디터 | 최대 2,000자까지 입력 가능하며, 볼드·기울임·밑줄·취소선·링크 삽입 서식을 지원합니다. |
| select (목록 선택) | 드롭다운 형태 | 최대 10개까지 옵션을 만들 수 있어요. |
| segmented-control (옵션 버튼) | 탭 형태 | 최대 4개의 옵션 중 하나를 선택할 수 있어요. 옵션명은 최대 8글자이며, 첫 번째 옵션이 기본값으로 설정됩니다. |
| switch (스위치) | ON/OFF 토글 | 기본값은 ON이에요. |
| color-picker (색상 선택) | 색상 및 투명도 선택 | 디폴트 색상과 투명도 설정이 필수이며, 설정하지 않으면 #000000, 투명도 100%가 기본값이에요. |
| image-uploader (이미지 업로더) | 이미지 업로드 | 용량 100MB, 크기 8,000px 이하의 이미지를 지원하며 mp4 영상은 제외돼요. |
| date-picker (날짜 선택) | 날짜 선택 | 기본값은 오늘 날짜이며, 이전 날짜는 선택할 수 없습니다. |
| time-picker (시간 선택) | 시간 선택 | 기본값은 오전 00시 00분입니다. |
| 아이템 (반복 항목) | 동일한 구조의 항목을 반복적으로 추가 | 제품 카드 리스트, 팀원 소개, 이미지 슬라이더 등 같은 형태의 콘텐츠를 여러 개 만들어야 할 때 사용합니다. |
2-3. 아이템 컴포넌트
아이템은 부모 아이템(parent item)과 자식 아이템(child item)으로 구성돼요. 부모 아이템은 반복 그룹 자체를 의미하고, 자식 아이템은 반복되는 개별 항목을 의미합니다. 각 자식 아이템 안에는 입력창, 이미지 업로더, 색상 선택 등 다른 컴포넌트를 하위 속성으로 넣을 수 있어요.
아이템의 제한 사항:
- 부모 아이템은 한 위젯에 최대 1개만 사용할 수 있어요.
- 자식 아이템은 최대 20개까지 추가할 수 있어요.
- 각 자식 아이템의 하위 속성은 최대 20개까지 설정할 수 있어요.
- 자식 아이템의 변수 id는 부모 아이템과 독립적으로 작성합니다. (예:
banner.title이 아닌title로 작성) - 코드에서 반복문 작성 시 지정된 방식(Handlebars의 each 문법)만 사용 가능하며, 다른 방법으로 작성하면 렌더링에 실패할 수 있어요.
- 주석으로 아이템을 작성할 때
{{#each}}안에 각 필드 annotation과 루트@type item이 모두 필요해요. {{#each}}내부 annotation같은 블록 안에 각 필드 annotation과 루트
@type item이 모두 필요해요.{{!-- @name item-cards @type item @label "카드 목록" --}} {{#each item-cards}} {{!-- @name editor-title @type text-editor @default "<p>제목</p>" @label "항목 제목" --}} <h2>{{editor-title}}</h2> {{!-- @name image-thumbnail @type image @label "이미지" --}} <img src="{{image-thumbnail}}" alt="" /> {{/each}}💡 참고: 각{{#each}}블록은 독립된 annotation 스코프를 가져요. 서로 다른{{#each}}안에서는 같은@name을 사용해도 됩니다.
3. 코드 위젯과의 차이
기존 코드 위젯과 커스텀 위젯은 다음과 같은 차이가 있어요.
코드 위젯
코드 위젯은 HTML, JavaScript, CSS 등 클라이언트 사이드 언어를 지원하며, 입력한 코드를 페이지에 그대로 출력하는 방식으로 동작해요. 주로 시각적으로 보이지 않는 스크립트 삽입 용도로 활용됩니다.
코드 위젯은 아임웹 전역 스타일과 격리되어 있지 않아요. 그래서 아래와 같은 특징이 있습니다.
- 아임웹에서 기본으로 적용하는 스타일(예: h1~h6 태그의 크기·간격 등)이 코드 위젯에도 그대로 반영돼요. 해당 스타일을 사용하지 않으려면 직접 초기화(unset)해야 합니다.
- 아임웹의 전역 스타일이나 기본 위젯에 영향을 주는 코드를 작성할 경우, 아임웹 업데이트 이후 정상적으로 동작하지 않을 수 있어요.
- 섹션 ID나 다른 위젯의 ID를 직접 호출해야 하는 경우가 많고, 이로 인해 의도치 않게 다른 위젯에 영향을 줄 수도 있어요.
- 디자인 모드에서는 코드가 실행되지 않고 빈 박스로 표시되기 때문에, 실제 결과를 확인하려면 미리보기 또는 게시 후 방문자 화면에서 확인해야 합니다.
커스텀 위젯
커스텀 위젯은 HTML+CSS+JS로 UI 위젯을 제작하며, 코드 위젯과 비교해 다음과 같은 차이가 있어요.
- 격리된 환경에서 동작해요. 아임웹의 전역 스타일이나 다른 위젯의 스타일이 커스텀 위젯에 영향을 주지 않고, 반대로 커스텀 위젯의 코드가 다른 위젯이나 페이지에 영향을 주지 않아요. 따라서 스타일 충돌이나 아임웹 업데이트로 인한 오작동 가능성이 크게 줄어듭니다.
- 아임웹의 공통 디자인 설정(폰트, 컬러 등)은 CSS 변수 형태로 제공돼요. 필요한 경우 가이드를 참고하여 코드에 직접 적용할 수 있습니다.
- 에디터의 미리보기에서 결과를 바로 확인할 수 있어요.
- 설정 패널을 제공하기 때문에 코드 수정 없이 디자인 모드에서 설정값을 변경할 수 있어요.
- 한 번 만든 위젯을 여러 사이트에 연동하여 재사용할 수 있습니다.