개발 툴바 앱 API
Astro 개발 툴바 앱 API를 사용하면 Astro 개발 툴바에 앱을 추가하는 Astro 통합을 생성할 수 있습니다. 이를 통해 새로운 기능을 추가하고 타사 서비스와 통합할 수 있습니다.
툴바 앱 통합 설정
섹션 제목: 툴바 앱 통합 설정통합은 astro:config:setup
후크의 개발 툴바에 앱을 추가할 수 있습니다.
addDevToolbarApp()
섹션 제목: addDevToolbarApp()astro:config:setup
후크에 사용할 수 있는 개발 툴바 앱을 추가하는 함수입니다. 개발 툴바 앱을 정의하려면 다음과 같은 필수 속성이 있는 객체를 사용합니다: id
, name
, icon
, entrypoint
.
앱의 고유 식별자입니다. 이는 후크 및 이벤트에서 앱을 고유하게 식별하는 데 사용됩니다.
name
섹션 제목: name앱의 이름입니다. 이는 사람이 읽을 수 있는 이름을 사용하여 앱을 참조해야 할 때마다 사용자에게 표시됩니다.
icon
섹션 제목: icon개발 툴바에 앱을 표시하는 데 사용되는 아이콘입니다. 이는 아이콘 목록의 아이콘이거나 아이콘의 SVG 마크업을 포함하는 문자열일 수 있습니다.
entrypoint
섹션 제목: entrypoint개발 툴바 앱을 내보내는 파일의 경로입니다.
개발 툴바 앱의 구조
섹션 제목: 개발 툴바 앱의 구조개발 툴바 앱은 astro/toolbar
모듈에서 사용할 수 있는 defineToolbarApp()
함수를 사용하여 객체에 기본 내보내기 (default exports)를 사용하는 .js
또는 .ts
파일입니다.
defineToolbarApp()
섹션 제목: defineToolbarApp()
Added in:
astro@4.7.0
개발 툴바 앱이 로드되고 꺼질 때 논리를 정의하는 함수입니다.
이 함수는 개발 툴바 앱이 로드될 때 호출되는 init()
함수가 있는 객체를 사용합니다. 또한 툴바 앱을 클릭하여 활성 상태를 끌 때 실행되는 beforeTogglingOff()
함수를 사용할 수도 있습니다.
init()
섹션 제목: init()시그니처: init(canvas: ShadowRoot, app: ToolbarAppEventTarget, server: ToolbarServerHelpers) => void
필수는 아니지만 대부분의 앱은 이 함수를 사용하여 앱의 핵심 동작을 정의합니다. 이 함수는 앱이 로드될 때 한 번만 호출됩니다. 어느 것이 먼저 나타나는지에 따라 브라우저가 유휴 상태일 때나 사용자가 UI에서 앱을 클릭할 때 호출됩니다.
이 함수는 앱 로직을 정의하기 위해 세 가지 인수를 전달받습니다: canvas
(요소를 화면에 렌더링하기 위해), app
(개발 툴바에서 클라이언트 측 이벤트를 주고 받기 위해), server
(서버와 통신하기 위해)
canvas
섹션 제목: canvas앱이 UI를 렌더링하는 데 사용할 수 있는 표준 ShadowRoot입니다. 표준 DOM API를 사용하여 요소를 생성하고 ShadowRoot에 추가할 수 있습니다.
모든 앱은 UI 렌더링을 위해 전용 ShadowRoot를 받습니다. 또한 상위 요소는 position: absolute;
를 사용하여 배치되므로 앱 UI는 Astro 페이지의 레이아웃에 영향을 미치지 않습니다.
app
섹션 제목: app
Added in:
astro@4.7.0
개발 툴바에서 이벤트를 주고 받을 수 있는 몇 가지 추가 클라이언트 측 이벤트 도우미가 포함된 표준 EventTarget
입니다.
server
섹션 제목: server
Added in:
astro@4.7.0
서버와 통신하는데 사용할 수 있는 객체입니다.
beforeTogglingOff()
섹션 제목: beforeTogglingOff()시그니처: beforeTogglingOff(canvas: ShadowRoot): boolean | void
astro@4.7.0
이 선택적 함수는 사용자가 UI에서 앱 아이콘을 클릭하여 앱을 끌 때 호출됩니다. 예를 들어 이 함수은 정리 작업을 수행하거나 앱을 끄기 전에 사용자에게 확인을 요청하는 데 사용할 수 있습니다.
잘못된 값이 반환되면 토글 끄기가 취소되고 앱은 계속 활성화됩니다.
canvas
섹션 제목: canvas앱의 ShadowRoot는 닫기 전에 필요한 UI를 렌더링하는 데 사용할 수 있습니다. init
함수의 canvas
인수와 동일합니다.
클라이언트 측 이벤트
섹션 제목: 클라이언트 측 이벤트EventTarget
(addEventListener
, dispatchEvent
, removeEventListener
등)의 표준 메서드 외에도 app
객체에는 다음과 같은 메서드도 있습니다:
onToggled()
섹션 제목: onToggled()시그니처: onToggled(callback: (options: {state: boolean})) => void
astro@4.7.0
사용자가 앱을 켜거나 끄기 위해 UI에서 앱 아이콘을 클릭할 때 호출될 콜백을 등록합니다.
onToolbarPlacementUpdated()
섹션 제목: onToolbarPlacementUpdated()시그니처: onToolbarPlacementUpdated(callback: (options: {placement: 'bottom-left' | 'bottom-center' | 'bottom-right'})) => void
astro@4.7.0
이 이벤트는 사용자가 개발 툴바의 배치를 변경할 때 시작됩니다. 예를 들어 툴바가 이동될 때 앱의 UI 위치를 변경하는 데 사용할 수 있습니다.
toggleState()
섹션 제목: toggleState()시그니처: toggleState(options: {state: boolean}) => void
astro@4.7.0
앱의 상태를 변경합니다. 예를 들어 사용자가 앱 UI에서 버튼을 클릭할 때 프로그래밍 방식으로 앱을 활성화하거나 비활성화하는 데 사용할 수 있습니다.
toggleNotification()
섹션 제목: toggleNotification()시그니처: toggleNotification(options: {state?: boolean, level?: 'error' | 'warning' | 'info'}) => void
astro@4.7.0
앱 아이콘의 알림을 전환합니다. 이는 사용자에게 앱에 주의가 필요함을 알리거나 현재 알림을 제거하는 데 사용될 수 있습니다.
state: boolean
섹션 제목: state: boolean앱에 사용자에 대한 알림이 있는지 여부를 나타냅니다. true
인 경우 앱 아이콘이 강조 표시됩니다. 반대로 false
인 경우 강조 표시가 제거됩니다. 이 속성을 지정하지 않으면 true
로 가정됩니다.
level: 'error' | 'warning' | 'info'
섹션 제목: level: 'error' | 'warning' | 'info'알림 수준을 나타냅니다. 이는 앱 아이콘 강조 표시의 색상과 모양 (진한 분홍색 원, 금색 삼각형 또는 파란색 사각형)을 결정하는 데 사용됩니다. 이 속성을 지정하지 않으면 'error'
로 간주됩니다.
클라이언트-서버 통신
섹션 제목: 클라이언트-서버 통신클라이언트-서버 통신을 위한 Vite의 방법을 사용하면 개발 툴바 앱과 서버가 서로 통신할 수 있습니다. 사용자 정의 메시지를 쉽게 주고받을 수 있도록 개발 툴바 앱 (클라이언트)과 통합 (서버) 모두에서 사용할 수 있는 도우미 메서드가 제공됩니다.
클라이언트에서
섹션 제목: 클라이언트에서앱에서 init()
후크의 server
객체를 사용하여 서버와 메시지를 주고받습니다.
send()
섹션 제목: send()시그니처: send<T>(event: stringify, data: T) => void
astro@4.7.0
개발 툴바 앱에 정의된 로직에서 서버로 데이터를 보냅니다.
클라이언트에서 서버로 메시지를 보낼 때 메시지를 수신할 수 있는 다른 앱이나 다른 통합과의 충돌을 피하기 위해 이벤트 이름 앞에 앱 ID나 다른 네임스페이스를 붙이는 것이 좋습니다.
on()
섹션 제목: on()시그니처: on<T>(event: string, callback: (data: T) => void) => void
astro@4.7.0
서버가 지정된 이벤트와 함께 메시지를 보낼 때 호출될 콜백을 등록합니다.
서버에서
섹션 제목: 서버에서툴바 앱을 추가하는 통합과 같은 통합에서는 앱에서 메시지를 주고받기 위한 toolbar
객체에 액세스하기 위해 astro:server:setup
후크을 사용하세요.
send()
섹션 제목: send()시그니처: send<T>(event: string, data: T) => void
astro@4.7.0
클라이언트에 데이터를 보냅니다.
on()
섹션 제목: on()시그니처: on<T>(event: string, callback: (data: T) => void) => void
astro@4.7.0
클라이언트가 지정된 이벤트와 함께 메시지를 보낼 때 호출될 콜백을 등록합니다.
onInitialized()
섹션 제목: onInitialized()시그니처: onInitialized(appId: string, callback: () => void) => void
astro@4.7.0
앱 초기화 시 호출할 콜백을 등록합니다.
Vite의 내장 connection
이벤트는 개발 툴바 앱이 초기화되기 전에 발생하므로 앱에서 직접 사용할 수 없습니다. onInitialized
메서드를 사용하여 메시지를 보내기 전에 앱이 완전히 초기화되었는지 확인하세요.
onAppToggled()
섹션 제목: onAppToggled()시그니처: onAppToggled(appId: string, callback: (options: {state: boolean}) => void) => void
astro@4.7.0
사용자가 앱을 켜거나 끄기 위해 UI에서 앱 아이콘을 클릭할 때 호출될 콜백을 등록합니다.
컴포넌트 라이브러리
섹션 제목: 컴포넌트 라이브러리개발 툴바에는 일관된 모양과 느낌으로 앱을 구축하는 데 사용할 수 있는 웹 컴포넌트 세트가 포함되어 있습니다.
astro-dev-toolbar-window
섹션 제목: astro-dev-toolbar-window창을 표시합니다.
컴포넌트의 슬롯이 창의 콘텐츠로 사용됩니다.
JavaScript를 사용하여 창을 만들 때 슬롯 콘텐츠는 컴포넌트의 가벼운 DOM에 들어가야 합니다.
astro-dev-toolbar-button
섹션 제목: astro-dev-toolbar-button버튼을 표시합니다.
컴포넌트의 슬롯이 버튼의 콘텐츠로 사용됩니다.
size
섹션 제목: size버튼의 크기 (small
, medium
, large
)
button-style
섹션 제목: button-style버튼의 스타일 (ghost
, outline
, purple
, gray
, red
, green
, yellow
, blue
). ghost
를 사용하면 버튼 자체가 보이지 않고 버튼의 내용만 표시됩니다.
JavaScript에서 기본 style
속성과의 충돌을 방지하려면 buttonStyle
속성을 사용하여 이 속성을 설정하세요.
button-border-radius
섹션 제목: button-border-radius
Added in:
astro@4.8.0
버튼의 테두리 반경입니다 (normal
, rounded
). rounded
를 사용하면 버튼의 모서리가 둥글게 되고 모든 면에 균일한 패딩이 적용됩니다.
JavaScript에서는 buttonBorderRadius
속성을 사용하여 이 속성을 설정합니다.
astro-dev-toolbar-badge
섹션 제목: astro-dev-toolbar-badge배지를 표시합니다.
컴포넌트의 슬롯은 배지의 콘텐츠로 사용됩니다.
size
섹션 제목: size배지의 크기 (small
, large
).
badge-style
섹션 제목: badge-style배지의 스타일 (색상) (purple
, gray
, red
, green
, yellow
, blue
).
JavaScript에서 기본 style
속성과의 충돌을 방지하려면 badgeStyle
속성을 사용하여 이 속성을 설정하세요.
astro-dev-toolbar-card
섹션 제목: astro-dev-toolbar-card카드를 보여줍니다. 카드가 <a>
요소처럼 작동하도록 하려면 선택적 link
속성을 지정하세요.
JavaScript를 사용하여 카드를 만들 때 clickAction
속성을 지정하여 카드가 <button>
요소처럼 작동하도록 할 수 있습니다.
컴포넌트의 슬롯이 카드의 콘텐츠로 사용됩니다.
card-style
섹션 제목: card-style카드의 스타일 (purple
, gray
, red
, green
, yellow
, blue
). 색상은 마우스 오버 시 카드 테두리에만 적용됩니다.
JavaScript에서는 cardStyle
을 사용하여 이 속성을 설정합니다.
astro-dev-toolbar-toggle
섹션 제목: astro-dev-toolbar-toggle체크박스 역할을 하는 토글 요소를 표시합니다. 이 요소는 내부적으로 기본 <input type="checkbox">
요소를 둘러싼 간단한 래퍼입니다. 체크박스 요소는 input
속성을 사용하여 접근할 수 있습니다.
astro-dev-toolbar-radio-checkbox
섹션 제목: astro-dev-toolbar-radio-checkbox
Added in:
astro@4.8.0
라디오 체크박스를 표시합니다. astro-dev-toolbar-toggle
컴포넌트와 유사하게 이 요소는 기본 <input type="radio">
요소를 둘러싼 간단한 래퍼입니다. 라디오 요소는 input
속성을 사용하여 액세스할 수 있습니다.
toggle-style
섹션 제목: toggle-style토글의 스타일 (purple
, gray
, red
, green
, yellow
, blue
).
JavaScript에서는 toggleStyle
을 사용하여 이 속성을 설정합니다.
astro-dev-toolbar-highlight
섹션 제목: astro-dev-toolbar-highlight페이지의 요소를 강조 표시하는 데 사용할 수 있습니다. 대부분의 경우 top
, left
, width
, height
CSS 속성을 사용하여 강조 표시하려는 요소와 일치하도록 이 요소의 위치를 지정하고 크기를 조정해야 합니다.
style
섹션 제목: style강조 표시의 스타일 (purple
, gray
, red
, green
, yellow
, blue
).
icon
섹션 제목: icon강조 표시의 오른쪽 상단에 표시할 아이콘입니다.
astro-dev-toolbar-tooltip
섹션 제목: astro-dev-toolbar-tooltip다양한 섹션이 포함된 툴팁을 표시합니다. 이 컴포넌트는 기본적으로 display: none;
으로 설정되어 있으며 data-show="true"
속성을 사용하여 표시할 수 있습니다.
섹션은 sections
속성을 사용하여 정의됩니다. 이 속성은 다음과 같은 형태의 객체 배열입니다.
이 컴포넌트는 강조 표시된 요소를 마우스로 가리키면 툴팁을 표시하기 위해 astro-dev-toolbar-highlight
컴포넌트와 결합되는 경우가 많습니다.
astro-dev-toolbar-icon
섹션 제목: astro-dev-toolbar-icon아이콘을 표시합니다. 아이콘 목록의 아이콘은 icon
속성을 사용하여 지정하거나 아이콘의 SVG 마크업을 슬롯으로 전달할 수 있습니다.
아이콘
섹션 제목: 아이콘현재 다음 아이콘을 사용할 수 있으며 아이콘을 허용하는 모든 컴포넌트에서 사용할 수 있습니다.
astro:logo
warning
arrow-down
bug
file-search
check-circle
gear
lightbulb
checkmark
dots-three
copy
위의 모든 아이콘에는 기본적으로 fill="currentColor"
가 설정되어 있으며 상위 요소에서 색상을 상속합니다.