Kakao Work::Block Kit 구성 및 정책::Button Block

페이지 이동경로

Button Block

Button Block(버튼 블록)은 말풍선에서 버튼을 표현하는 블록으로, 레이아웃 블록을 구성하는 엘리먼트의 속성으로 사용되기도 합니다. 중첩하여 사용할 경우 네 개 이상의 버튼 사용은 지양하며, 더 중요한 버튼을 상단에 위치시키는 것을 권장합니다. 버튼명은 직관적인 명칭으로 가능하면 짧은 명사형을 사용하고, 버튼의 Action Type에 따라 적당한 버튼명을 사용해야 합니다.
Button Block 정책에 관한 자세한 설명은 정책 및 UX 가이드 문서를 참고하시기 바랍니다.

Button Block
블록 유형 블록명 엘리먼트 레이아웃 블록
말풍선 Button Block O X

기능 소개

한 개의 행에 한 개의 버튼을 표현할 때 사용하며, 여러 개의 Button Block을 연속하여 쌓는 것도 가능합니다.

버튼 표현

한 개의 행에 한 개의 버튼을 표현합니다.

버튼 표현 예시

그림버튼 표현 예시

색상

총 세 개의 버튼 색상을 제공합니다.

  • default(일반적인 표현)
  • primary(우선순위로 강조)
  • danger(위험, 경고의 표현)

버튼 색상 예시

그림버튼 색상 예시



버튼 및 중첩 표시

버튼

  • 최대 20자까지 입력
  • 버튼 사이즈에 따라 말줄임 처리
  • 가운데 정렬로 표시

중첩 표시

  • Button Block을 연속하여 쌓으면, 긴 형태의 버튼 라인 표현이 가능합니다.

버튼 및 중첩 예시

그림버튼 및 중첩 예시

블록 속성

Button Block은 버튼을 클릭했을 때 수행되는 동작에 따라 기본 동작을 수행하는 Compatibility와 기본 동작이 아닌 OS/플랫폼별 다른 동작을 수행하는 Exclusive 속성으로 구분됩니다.

카카오워크 1.11 버전 이후부터 Button Block의 표준 포맷이 다음과 같이 변경되었습니다.

  • OS 또는 플랫폼 별로 다른 동작 수행을 설정할 수 있는 Exclusive 속성 추가
Button 블록 속성
속성 타입 필수 여부 설명
type String 필수 타입 고정값
- button으로 고정
text String 필수 버튼 레이블
style String 필수 버튼 스타일
default: 일반적인 표현
primary: 우선순위로 강조
danger: 위험, 경고의 표현
action Object 필수 버튼 선택 시 수행할 동작 정의
Compatability: 기본 동작을 수행하는 경우
Exclusive: 운영체제(OS)나 플랫폼 별로 다른 동작을 수행하는 경우

안내
한 개의 행에 여러 버튼을 표현하고 싶은 경우에는 레이아웃 블록인 Action Block을 활용합니다.

  • Button Block 정책에 대한 자세한 설명은 정책 및 UX 가이드 문서를 참고하시기 바랍니다.

Compatability Action

버튼의 기본적인 동작을 정의합니다.

블록 속성
속성 타입 필수 여부 설명
type String 필수 버튼 선택 시 수행할 동작 명령어
open_system_browser: value 속성값의 URL을 시스템 브라우저로 연결
open_inapp_browser: value 속성값의 URL을 인앱브라우저로 연결
open_external_app: value 속성값의 커스텀 앱 스킴(Custom App Scheme)을 호출
call_modal: Modal 창을 띄우는 요청
- value 속성값을 서버에 요청하여 이에 해당하는 Modal 데이터를 표시
submit_action: action_name, value, 문맥 정보를 고객사 서버에 콜백으로 전달
- 해당 속성 사용 시, name 속성은 필수로 설정
name String 선택 사용자가 여러 액션 엘리먼트 중에 어떤 버튼을 클릭했는지 구분하는데 사용
- 주로 서버 API 호출 시에 사용
- submit_action 타입을 사용 시, 필수로 설정
value String 필수 버튼의 액션 수행 시 추가 정보를 담을 수 있는 속성
- 자유 포맷으로 Query Parameter, String Encoded JSON 등 사용 가능

open_system_browser

action의 type을 open_system_browser로 설정하면 value 속성값의 URL을 시스템 브라우저로 연결할 수 있습니다.

코드예제open_system_browser Sample Code

{
   "type": "button",
   "text": "자세히보기",
   "style": "primary",
   "action": {
         "type": "open_system_browser",
         "name": "button1",
         "value": "http://example.com/details/999"
      }
}

open_inapp_browser

action의 type을 open_inapp_browser로 설정하면 value 속성값의 URL을 카카오워크 내부 팝업으로 호출할 수 있습니다.

코드예제open_inapp_browser Sample Code

{
    "type": "button",
    "text": "자세히보기",
    "style": "primary",
    "action": {
         "type": "open_inapp_browser",
         "name": "button1",
         "value": "http://example.com/details/999"
      }
}

open_external_app

action의 type을 open_external_app로 설정하면 value 속성값의 커스텀 앱 스킴(Custom App Scheme)을 호출할 수 있습니다.

코드예제open_external_app Sample Code

{
   "type": "button",
   "text": "카카오 지도에서 보기",
   "action": {
         "type":"open_external_app",
         "value": "ios=kakaomap%3A%2F%2Flook%3Fp%3D37.537229%2C127.005515&aos=kakaomap%3A%2F%2Flook%3Fp%3D37.537229%2C127.005515"
      }
}

주의
사용자의 디바이스 플랫폼에 앱 스킴(App Scheme)에 해당하는 앱이 설치되어 있지 않을 수 있습니다.

  • Query String 형식을 이용해 각 플랫폼별 scheme을 담고 있는 value 속성에는 디바이스 플랫폼에 해당하는 값이 없을 수 있습니다.(iOS 앱만 제공하는 경우 등)

submit_action

action의 type을 submit_action로 설정 시, name과 value를 필수로 설정해야 합니다. 문맥 정보와 함께 name과 value 값을 고객사 서버에 콜백(Callback)으로 전달할 수 있으며, value 속성을 활용하면 다시 돌려 받기를 원하는 값을 자유롭게 설정할 수 있습니다. submit_action 속성을 활용한 Bot과 멤버 간 대화 시나리오는 반응형 메시지 문서를 참고하시기 바랍니다.

코드예제submit_action Sample Code

{
    "type": "button",
    "text": "일정 수락",
    "action": {
         "type": "submit_action",
         "name": "accept",
         "value":"event_id=20210301-0024"    
      }   
}

안내
Block Kit을 활용한 다양한 메시지 시나리오는 Bot 메시지 시나리오 문서를 참고하시기 바랍니다.

call_modal

action의 type을 call_modal로 설정하면, 버튼 클릭 시 Modal을 화면에 띄우고 사전에 등록한 Bot의 Request URL로 Modal안에 표시할 블록 데이터를 요청합니다. value 속성을 활용하여 다시 돌려받길 원하는 값으로 자유롭게 설정할 수 있습니다. call_modal 속성을 활용한 Bot과 멤버 간 대화 시나리오는 반응형 Modal 문서를 참고하시기 바랍니다.

코드예제call_modal Sample Code

{
    "type": "button",
    "text": "결재창 띄우기",
    "action":{
         "type": "call_modal",
         "value":"number=20200401-PR-0024"
      }
}

안내
Block Kit을 활용한 다양한 메시지 시나리오는 Bot 메시지 시나리오 문서를 참고하시기 바랍니다.

  • Button Block 정책에 대한 자세한 설명은 정책 및 UX 가이드 문서를 참고하시기 바랍니다.

Exclusive Action

exclusive 속성을 적용하여 특정 플랫폼(PC, Mobile) 또는 특정 OS(Windows, macOS, Android, iOS) 별로 다른 동작을 설정할 수 있습니다. 설정은 OS, 플랫폼, default순으로 적용합니다.

블록 속성
속성 타입 필수 여부 설명
type String 필수 타입 고정 값
- exclusive로 고정
default Object 필수 기본 실행
- Compatability를 참고하여 블록 속성 추가
pc Object 선택 PC에서 실행하는 경우
- Compatability를 참고하여 블록 속성 추가
mobile Object 선택 Mobile에서 실행하는 경우
- Compatability를 참고하여 블록 속성 추가
windows Object 선택 Windows에서 실행하는 경우
- Compatability를 참고하여 블록 속성 추가
macos Object 선택 macOS에서 실행하는 경우
- Compatability를 참고하여 블록 속성 추가
android Object 선택 Android에서 실행하는 경우
- Compatability를 참고하여 블록 속성 추가
ios Object 선택 iOS에서 실행하는 경우
- Compatability를 참고하여 블록 속성 추가

코드예제exclusive Sample Code

{
   "type": "button",
   "text": "자세히보기",
   "style": "primary",
   "action": {
         "type": "exclusive",
         "default": {
            "type": "open_system_browser",
            "value": "https://example.com"
         },
         "ios": {
            "type": "open_inapp_browser",
            "value": "http://m.example.com"
         },
         "android": {
            "type": "open_external_app",
            "value": "geo:37.537229,127.005515"
         }
   }
}

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.