(고급) 커스텀 위젯에 공통 디자인 설정값 적용하기

커스텀 위젯에서 --imweb- 으로 시작하는 CSS 변수를 사용하면 사이트에 설정된 글꼴, 색상, 버튼 스타일을 위젯에 그대로 적용할 수 있습니다.

사이트 디자인 설정을 변경하면 위젯도 함께 바뀌기 때문에, 위젯을 여러 사이트에 연동하거나 사이트 색상을 바꿀 때마다 위젯 코드를 수정할 필요가 없습니다. 이 도움말에서는 사용 방법과 사용할 수 있는 변수 전체 목록을 알아보실 수 있습니다.

목차

1. 사용 방법
2. 사용할 수 있는 변수
3. 값이 예상과 다르게 보이는 경우
4. --unit-style- 변수는 사용할 수 없습니다
5. 자주 묻는 질문

1. 사용 방법

위젯 CSS에서 var() 로 변수를 불러오면 됩니다.

.my-button {
  background-color: var(--imweb-button-background-color);
  color:            var(--imweb-button-text-color);
  border:           var(--imweb-button-border-width) solid var(--imweb-button-border-color);
  border-radius:    var(--imweb-button-radius);
  font-weight:      var(--imweb-button-font-weight);
}

.my-widget h2 {
  font-family: var(--imweb-font-family-heading);
}

폴백 값을 따로 지정하지 않아도 됩니다. --imweb- 변수는 항상 존재하며, 값은 항상 유효한 CSS 값입니다. 사이트에서 해당 항목을 설정하지 않았거나 기능을 꺼 둔 경우에도 아임웹이 대신할 값을 채워서 내보냅니다.

같은 이유로 값이 있는지 확인하는 코드도 필요하지 않습니다. 아래처럼 쓰지 않아도 됩니다.

/* 이렇게 쓸 필요가 없습니다 */
background-color: var(--imweb-button-background-color, #000000);

단위 계산도 필요하지 않습니다. 값은 980px, bold, italic 처럼 단위와 실제 값까지 완성된 상태로 전달되므로, calc() 로 감싸거나 단위를 붙이지 않고 그대로 사용합니다.

2. 사용할 수 있는 변수

총 31개의 변수를 사용할 수 있습니다. 이름은 --imweb-{그룹}-{속성} 형식이며, 그룹은 글꼴(font), 색상(color), 레이아웃(layout), 버튼(button), 강조 버튼(button-emphasis) 다섯 가지입니다.

아래 표의 값은 위젯 CSS에 그대로 붙여넣을 수 있는 형태로 적었습니다.

2-1. 글꼴 (2개)

글꼴 변수에는 영문, 한글, 기본 폴백이 합쳐진 글꼴 스택이 들어갑니다. 사이트 디자인 설정의 "본문 한/중/일"과 "본문 영문"을 각각 따로 불러올 수는 없습니다.

제목 글꼴을 지정하지 않은 사이트에서는 var(--imweb-font-family-heading) 에 본문 글꼴 스택이 들어갑니다. 이 경우 아임웹 기본 화면도 제목을 본문 글꼴로 표시하므로 결과가 같습니다.

2-2. 색상 (5개)

2-3. 레이아웃 (2개)

2-4. 버튼 (14개)

• var(--imweb-button-radius) 에는 사이트의 "버튼 스타일"(각진 형태, 완전히 둥근 형태) 설정이 이미 반영된 px 값이 들어갑니다.
• var(--imweb-button-font-weight) 의 값은 bold 또는 normal 입니다.
• var(--imweb-button-font-style) 의 값은 italic 또는 normal 입니다.

2-5. 강조 버튼 (8개)

사이트 디자인 설정의 "강조 버튼 사용" 스위치는 변수로 전달되지 않습니다. 스위치가 꺼져 있는 사이트에서는 강조 버튼 변수에 일반 버튼 값이 들어갑니다.

3. 값이 예상과 다르게 보이는 경우

아래 세 가지는 변수 자체는 정상적으로 전달되지만, 아임웹 기본 화면과 다르게 보일 수 있습니다.

그리드 간격(좌우)

var(--imweb-layout-grid-margin-x) 는 실제 사이트 화면에 거의 반영되지 않는 설정입니다. 값을 사용하면 기대한 간격과 다르게 보일 수 있으므로, 위젯의 간격은 직접 지정하는 편을 권장합니다.

버튼 글자 크기

var(--imweb-button-font-size) 값을 바꿔도 아임웹 기본 버튼의 글자 크기는 바뀌지 않습니다. 아임웹 기본 버튼은 내부에 고정된 크기를 사용하기 때문입니다. 이 변수는 위젯 안에서만 의미가 있습니다.

강조 버튼 스위치가 꺼진 사이트

강조 버튼 스위치가 꺼져 있으면 강조 버튼 변수에 일반 버튼 값이 들어갑니다. 반면 아임웹 기본 화면은 이때 강조 버튼을 브랜드 색으로 표시합니다. 따라서 사이트가 일반 버튼 색을 따로 변경한 경우, 위젯의 강조 버튼 색과 아임웹 기본 화면의 강조 버튼 색이 서로 다르게 보일 수 있습니다.

4. --unit-style- 변수는 사용할 수 없습니다

--unit-style- 으로 시작하는 변수도 함께 전달되지만, 이는 아임웹 내부에서 사용하는 값입니다.

구분 방법은 간단합니다. 대시 사이의 첫 단어가 imweb 이면 위젯에서 사용할 수 있는 변수이고, unit-style 이면 내부용 변수입니다.

같은 값이 필요하다면 2번 항목의 --imweb- 변수를 사용해 주세요. 단위와 실제 값까지 완성된 상태로 전달됩니다.

5. 자주 묻는 질문

Q1. 변수 값이 비어 있는 경우도 있나요?

A1. 아니요, --imweb- 변수는 항상 존재하며 값도 항상 유효한 CSS 값입니다. 사이트에서 해당 항목을 설정하지 않았거나 기능을 꺼 둔 경우의 값은 아임웹이 대신 채워서 내보냅니다. 위젯 CSS에서 폴백 값을 지정하거나 값이 있는지 확인할 필요가 없습니다.

Q2. 사이트 디자인 설정을 바꾸면 위젯도 바로 바뀌나요?

A2. 네, 만약 위의 코드를 css 변수로 사용할 경우 위젯이 연동된 사이트의 디자인 설정을 변경하면 변경된 값이 위젯에도 적용됩니다. 위젯 코드를 다시 수정하거나 업데이트할 필요가 없습니다.

Q3. 하나의 위젯을 여러 사이트에 연동하면 어떻게 되나요?

A3. 각 사이트의 디자인 설정값이 적용됩니다. 같은 위젯이라도 사이트마다 글꼴과 색상이 다르게 보입니다.

Q4. --imweb- 변수 대신 색상 값을 직접 입력해도 되나요?

A4. 네, 직접 입력해도 위젯은 정상적으로 동작합니다. 다만 사이트 디자인 설정을 변경해도 위젯 색상은 바뀌지 않으므로, 사이트마다 다르게 보여야 하는 값이라면 변수를 사용하는 편을 권장합니다.

함께 보면 좋은 가이드

• 관련 가이드: 커스텀 위젯 스튜디오란?
• 관련 가이드: 커스텀 위젯 만들기