컨텐츠로 건너뛰기

개발 툴바 앱 API

Astro 개발 툴바 앱 API를 사용하면 Astro 개발 툴바에 앱을 추가하는 Astro 통합을 생성할 수 있습니다. 이를 통해 새로운 기능을 추가하고 타사 서비스와 통합할 수 있습니다.

통합은 astro:config:setup 후크의 개발 툴바에 앱을 추가할 수 있습니다.

my-integration.js
/**
* @type {() => import('astro').AstroIntegration}
*/
export default () => ({
name: "my-integration",
hooks: {
"astro:config:setup": ({ addDevToolbarApp }) => {
addDevToolbarApp({
id: "my-app",
name: "My App",
icon: "<svg>...</svg>",
entrypoint: "./my-app.js",
});
},
},
});

astro:config:setup 후크에 사용할 수 있는 개발 툴바 앱을 추가하는 함수입니다. 개발 툴바 앱을 정의하려면 다음과 같은 필수 속성이 있는 객체를 사용합니다: id, name, icon, entrypoint.

앱의 고유 식별자입니다. 이는 후크 및 이벤트에서 앱을 고유하게 식별하는 데 사용됩니다.

my-integration.js
{
id: 'my-app',
// ...
}

앱의 이름입니다. 이는 사람이 읽을 수 있는 이름을 사용하여 앱을 참조해야 할 때마다 사용자에게 표시됩니다.

my-integration.js
{
// ...
name: 'My App',
// ...
}

개발 툴바에 앱을 표시하는 데 사용되는 아이콘입니다. 이는 아이콘 목록의 아이콘이거나 아이콘의 SVG 마크업을 포함하는 문자열일 수 있습니다.

my-integration.js
{
// ...
icon: '<svg>...</svg>', // 또는 예를 들어 'astro:logo'
// ...
}

개발 툴바 앱을 내보내는 파일의 경로입니다.

my-integration.js
{
// ...
entrypoint: './my-app.js',
}

개발 툴바 앱은 astro/toolbar 모듈에서 사용할 수 있는 defineToolbarApp() 함수를 사용하여 객체에 기본 내보내기 (default exports)를 사용하는 .js 또는 .ts 파일입니다.

src/my-app.js
import { defineToolbarApp } from "astro/toolbar";
export default defineToolbarApp({
init(canvas) {
const text = document.createTextNode('Hello World!');
canvas.appendChild(text);
}
beforeTogglingOff() {
const confirmation = window.confirm('Really exit?');
return confirmation;
}
});

Added in: astro@4.7.0

개발 툴바 앱이 로드되고 꺼질 때 논리를 정의하는 함수입니다.

이 함수는 개발 툴바 앱이 로드될 때 호출되는 init() 함수가 있는 객체를 사용합니다. 또한 툴바 앱을 클릭하여 활성 상태를 끌 때 실행되는 beforeTogglingOff() 함수를 사용할 수도 있습니다.

시그니처: init(canvas: ShadowRoot, app: ToolbarAppEventTarget, server: ToolbarServerHelpers) => void

필수는 아니지만 대부분의 앱은 이 함수를 사용하여 앱의 핵심 동작을 정의합니다. 이 함수는 앱이 로드될 때 한 번만 호출됩니다. 어느 것이 먼저 나타나는지에 따라 브라우저가 유휴 상태일 때나 사용자가 UI에서 앱을 클릭할 때 호출됩니다.

이 함수는 앱 로직을 정의하기 위해 세 가지 인수를 전달받습니다: canvas (요소를 화면에 렌더링하기 위해), app(개발 툴바에서 클라이언트 측 이벤트를 주고 받기 위해), server(서버와 통신하기 위해)

앱이 UI를 렌더링하는 데 사용할 수 있는 표준 ShadowRoot입니다. 표준 DOM API를 사용하여 요소를 생성하고 ShadowRoot에 추가할 수 있습니다.

모든 앱은 UI 렌더링을 위해 전용 ShadowRoot를 받습니다. 또한 상위 요소는 position: absolute;를 사용하여 배치되므로 앱 UI는 Astro 페이지의 레이아웃에 영향을 미치지 않습니다.

src/my-app.js
export default defineToolbarApp({
init(canvas) {
canvas.appendChild(document.createTextNode('Hello World!'))
}
});

Added in: astro@4.7.0

개발 툴바에서 이벤트를 주고 받을 수 있는 몇 가지 추가 클라이언트 측 이벤트 도우미가 포함된 표준 EventTarget입니다.

src/my-app.js
export default defineToolbarApp({
init(canvas, app) {
app.onToggled(({ state }) => {
const text = document.createTextNode(
`The app is now ${state ? "enabled" : "disabled"}!`,
);
canvas.appendChild(text);
});
},
});

Added in: astro@4.7.0

서버와 통신하는데 사용할 수 있는 객체입니다.

src/my-app.js
export default defineToolbarApp({
init(canvas, app, server) {
server.send('my-message', { message: 'Hello!' });
server.on('server-message', (data) => {
console.log(data.message);
});
},
});

시그니처: beforeTogglingOff(canvas: ShadowRoot): boolean | void

Added in: astro@4.7.0

이 선택적 함수는 사용자가 UI에서 앱 아이콘을 클릭하여 앱을 끌 때 호출됩니다. 예를 들어 이 함수은 정리 작업을 수행하거나 앱을 끄기 전에 사용자에게 확인을 요청하는 데 사용할 수 있습니다.

잘못된 값이 반환되면 토글 끄기가 취소되고 앱은 계속 활성화됩니다.

src/my-app.js
export default defineToolbarApp({
// ...
beforeTogglingOff() {
const confirmation = window.confirm('Are you sure you want to disable this app?');
return confirmation;
}
});

앱의 ShadowRoot는 닫기 전에 필요한 UI를 렌더링하는 데 사용할 수 있습니다. init 함수의 canvas 인수와 동일합니다.

EventTarget (addEventListener, dispatchEvent, removeEventListener 등)의 표준 메서드 외에도 app 객체에는 다음과 같은 메서드도 있습니다:

시그니처: onToggled(callback: (options: {state: boolean})) => void

Added in: astro@4.7.0

사용자가 앱을 켜거나 끄기 위해 UI에서 앱 아이콘을 클릭할 때 호출될 콜백을 등록합니다.

src/my-app.js
app.onToggled((options) => {
console.log(`The app is now ${options.state ? 'enabled' : 'disabled'}!`);
});

시그니처: onToolbarPlacementUpdated(callback: (options: {placement: 'bottom-left' | 'bottom-center' | 'bottom-right'})) => void

Added in: astro@4.7.0

이 이벤트는 사용자가 개발 툴바의 배치를 변경할 때 시작됩니다. 예를 들어 툴바가 이동될 때 앱의 UI 위치를 변경하는 데 사용할 수 있습니다.

src/my-app.js
app.onToolbarPlacementUpdated((options) => {
console.log(`The toolbar is now placed at ${options.placement}!`);
});

시그니처: toggleState(options: {state: boolean}) => void

Added in: astro@4.7.0

앱의 상태를 변경합니다. 예를 들어 사용자가 앱 UI에서 버튼을 클릭할 때 프로그래밍 방식으로 앱을 활성화하거나 비활성화하는 데 사용할 수 있습니다.

src/my-app.js
app.toggleState({ state: false });

시그니처: toggleNotification(options: {state?: boolean, level?: 'error' | 'warning' | 'info'}) => void

Added in: astro@4.7.0

앱 아이콘의 알림을 전환합니다. 이는 사용자에게 앱에 주의가 필요함을 알리거나 현재 알림을 제거하는 데 사용될 수 있습니다.

src/my-app.js
app.toggleNotification({
state: true,
level: 'warning',
});

앱에 사용자에 대한 알림이 있는지 여부를 나타냅니다. true인 경우 앱 아이콘이 강조 표시됩니다. 반대로 false인 경우 강조 표시가 제거됩니다. 이 속성을 지정하지 않으면 true로 가정됩니다.

알림 수준을 나타냅니다. 이는 앱 아이콘 강조 표시의 색상과 모양 (진한 분홍색 원, 금색 삼각형 또는 파란색 사각형)을 결정하는 데 사용됩니다. 이 속성을 지정하지 않으면 'error'로 간주됩니다.

클라이언트-서버 통신을 위한 Vite의 방법을 사용하면 개발 툴바 앱과 서버가 서로 통신할 수 있습니다. 사용자 정의 메시지를 쉽게 주고받을 수 있도록 개발 툴바 앱 (클라이언트)과 통합 (서버) 모두에서 사용할 수 있는 도우미 메서드가 제공됩니다.

앱에서 init() 후크의 server 객체를 사용하여 서버와 메시지를 주고받습니다.

src/my-app.js
export default defineToolbarApp({
init(canvas, app, server) {
server.send('my-message', { message: 'Hello!' });
server.on('server-message', (data) => {
console.log(data.message);
});
},
});

시그니처: send<T>(event: stringify, data: T) => void

Added in: astro@4.7.0

개발 툴바 앱에 정의된 로직에서 서버로 데이터를 보냅니다.

src/my-app.js
init(canvas, app, server) {
server.send('my-app:my-message', { message: 'Hello!' });
}

클라이언트에서 서버로 메시지를 보낼 때 메시지를 수신할 수 있는 다른 앱이나 다른 통합과의 충돌을 피하기 위해 이벤트 이름 앞에 앱 ID나 다른 네임스페이스를 붙이는 것이 좋습니다.

시그니처: on<T>(event: string, callback: (data: T) => void) => void

Added in: astro@4.7.0

서버가 지정된 이벤트와 함께 메시지를 보낼 때 호출될 콜백을 등록합니다.

src/my-app.js
init(canvas, app, server) {
server.on('server-message', (data) => {
console.log(data.message);
});
}

툴바 앱을 추가하는 통합과 같은 통합에서는 앱에서 메시지를 주고받기 위한 toolbar 객체에 액세스하기 위해 astro:server:setup 후크을 사용하세요.

my-integration.js
export default () => ({
name: "my-integration",
hooks: {
"astro:config:setup": ({ addDevToolbarApp }) => {},
"astro:server:setup": ({ toolbar }) => {},
},
});

시그니처: send<T>(event: string, data: T) => void

Added in: astro@4.7.0

클라이언트에 데이터를 보냅니다.

my-integration.js
'astro:server:setup': ({ toolbar }) => {
toolbar.send('server-message', { message: 'Hello!' });
},

시그니처: on<T>(event: string, callback: (data: T) => void) => void

Added in: astro@4.7.0

클라이언트가 지정된 이벤트와 함께 메시지를 보낼 때 호출될 콜백을 등록합니다.

my-integration.js
'astro:server:setup': ({ toolbar }) => {
toolbar.on('my-app:my-message', (data) => {
console.log(data.message);
});
},

시그니처: onInitialized(appId: string, callback: () => void) => void

Added in: astro@4.7.0

앱 초기화 시 호출할 콜백을 등록합니다.

my-integration.js
'astro:server:setup': ({ toolbar }) => {
toolbar.onInitialized('my-app', () => {
console.log('The app is now initialized!');
});
},

시그니처: onAppToggled(appId: string, callback: (options: {state: boolean}) => void) => void

Added in: astro@4.7.0

사용자가 앱을 켜거나 끄기 위해 UI에서 앱 아이콘을 클릭할 때 호출될 콜백을 등록합니다.

my-integration.js
'astro:server:setup': ({ toolbar }) => {
toolbar.onAppToggled('my-app', ({ state }) => {
console.log(`The app is now ${state ? 'enabled' : 'disabled'}!`);
});
},

개발 툴바에는 일관된 모양과 느낌으로 앱을 구축하는 데 사용할 수 있는 웹 컴포넌트 세트가 포함되어 있습니다.

창을 표시합니다.

컴포넌트의 슬롯이 창의 콘텐츠로 사용됩니다.

<astro-dev-toolbar-window>
<p>My content</p>
</astro-dev-toolbar-window>

JavaScript를 사용하여 창을 만들 때 슬롯 콘텐츠는 컴포넌트의 가벼운 DOM에 들어가야 합니다.

const myWindow = document.createElement('astro-dev-toolbar-window');
const myContent = document.createElement('p');
myContent.textContent = 'My content';
// `myWindow.shadowRoot`가 아닌 `window`에서 직접 appendChild를 사용하세요.
myWindow.appendChild(myContent);

버튼을 표시합니다.

컴포넌트의 슬롯이 버튼의 콘텐츠로 사용됩니다.

const myButton = document.createElement('astro-dev-toolbar-button');
myButton.textContent = 'Click me!';
myButton.buttonStyle = "purple";
myButton.size = "medium";
myButton.addEventListener('click', () => {
console.log('Clicked!');
});

버튼의 크기 (small, medium, large)

버튼의 스타일 (ghost, outline, purple, gray, red, green, yellow, blue). ghost를 사용하면 버튼 자체가 보이지 않고 버튼의 내용만 표시됩니다.

JavaScript에서 기본 style 속성과의 충돌을 방지하려면 buttonStyle 속성을 사용하여 이 속성을 설정하세요.

배지를 표시합니다.

컴포넌트의 슬롯은 배지의 콘텐츠로 사용됩니다.

<astro-dev-toolbar-badge>My badge</astro-dev-toolbar-badge>

배지의 크기 (small, large).

배지의 스타일 (색상) (purple, gray, red, green, yellow, blue).

JavaScript에서 기본 style 속성과의 충돌을 방지하려면 badgeStyle 속성을 사용하여 이 속성을 설정하세요.

카드를 보여줍니다. 카드가 <a> 요소처럼 작동하도록 하려면 선택적 link 속성을 지정하세요.

JavaScript를 사용하여 카드를 만들 때 clickAction 속성을 지정하여 카드가 <button> 요소처럼 작동하도록 할 수 있습니다.

컴포넌트의 슬롯이 카드의 콘텐츠로 사용됩니다.

<astro-dev-toolbar-card icon="astro:logo" link="https://github.com/withastro/astro/issues/new/choose">Report an issue</astro-dev-toolbar-card>

카드의 스타일 (purple, gray, red, green, yellow, blue). 색상은 마우스 오버 시 카드 테두리에만 적용됩니다.

JavaScript에서는 cardStyle을 사용하여 이 속성을 설정합니다.

체크박스 역할을 하는 토글 요소를 표시합니다. 이 요소는 내부적으로 기본 <input type="checkbox"> 요소를 둘러싼 간단한 래퍼입니다. 체크박스 요소는 input 속성을 사용하여 접근할 수 있습니다.

const toggle = document.createElement('astro-dev-toolbar-toggle');
toggle.input.addEventListener('change', (evt) => {
console.log(`The toggle is now ${evt.currentTarget.checked ? 'enabled' : 'disabled'}!`);
});

토글의 스타일 (purple, gray, red, green, yellow, blue).

JavaScript에서는 toggleStyle을 사용하여 이 속성을 설정합니다.

페이지의 요소를 강조 표시하는 데 사용할 수 있습니다. 대부분의 경우 top, left, width, height CSS 속성을 사용하여 강조 표시하려는 요소와 일치하도록 이 요소의 위치를 ​​지정하고 크기를 조정해야 합니다.

<!-- Highlight the entire page -->
<astro-dev-toolbar-highlight style="top: 0; left: 0; width: 100%; height: 100%;"></astro-dev-toolbar-highlight>
const elementToHighlight = document.querySelector('h1');
const rect = elementToHighlight.getBoundingClientRect();
const highlight = document.createElement('astro-dev-toolbar-highlight');
highlight.style.top = `${Math.max(rect.top + window.scrollY - 10, 0)}px`;
highlight.style.left = `${Math.max(rect.left + window.scrollX - 10, 0)}px`;
highlight.style.width = `${rect.width + 15}px`;
highlight.style.height = `${rect.height + 15}px`;
highlight.icon = 'astro:logo';

강조 표시의 스타일 (purple, gray, red, green, yellow, blue).

강조 표시의 오른쪽 상단에 표시할 아이콘입니다.

다양한 섹션이 포함된 툴팁을 표시합니다. 이 컴포넌트는 기본적으로 display: none;으로 설정되어 있으며 data-show="true" 속성을 사용하여 표시할 수 있습니다.

섹션은 sections 속성을 사용하여 정의됩니다. 이 속성은 다음과 같은 형태의 객체 배열입니다.

{
title?: string; // 섹션 제목
inlineTitle?: string; // 섹션 제목, 제목 옆에 인라인으로 표시됨
icon?: Icon; // 섹션의 아이콘
content?: string; // 섹션의 내용
clickAction?: () => void | Promise<void>; // 섹션을 클릭할 때 수행할 작업
clickDescription?: string; // 섹션을 클릭할 때 수행할 작업에 대한 설명
}
const tooltip = document.createElement('astro-dev-toolbar-tooltip');
tooltip.sections = [{
title: 'My section',
icon: 'astro:logo',
content: 'My content',
clickAction: () => {
console.log('Clicked!')
},
clickDescription: 'Click me!'
}]

이 컴포넌트는 강조 표시된 요소를 마우스로 가리키면 툴팁을 표시하기 위해 astro-dev-toolbar-highlight 컴포넌트와 결합되는 경우가 많습니다.

const highlight = document.createElement('astro-dev-toolbar-highlight');
// 강조 표시 위치를 지정하세요.
const tooltip = document.createElement('astro-dev-toolbar-tooltip');
// 툴팁에 섹션 추가...
highlight.addEventListener('mouseover', () => {
tooltip.dataset.show = 'true';
});
highlight.addEventListener('mouseout', () => {
tooltip.dataset.show = 'false';
});

아이콘을 표시합니다. 아이콘 목록의 아이콘은 icon 속성을 사용하여 지정하거나 아이콘의 SVG 마크업을 슬롯으로 전달할 수 있습니다.

<astro-dev-toolbar-icon icon="astro:logo" />
<astro-dev-toolbar-icon>
<svg>...</svg>
</astro-dev-toolbar-icon>

현재 다음 아이콘을 사용할 수 있으며 아이콘을 허용하는 모든 컴포넌트에서 사용할 수 있습니다.

  • astro:logo
  • warning
  • arrow-down
  • bug
  • file-search
  • check-circle
  • gear
  • lightbulb
  • checkmark
  • dots-three
  • copy

위의 모든 아이콘에는 기본적으로 fill="currentColor"가 설정되어 있으며 상위 요소에서 색상을 상속합니다.