API de la barre d'outils de développement

L’API de la barre d’outils de développement d’Astro vous permet de créer des intégrations Astro qui ajoutent des applications à la barre d’outils de développement d’Astro. Cela vous permet d’ajouter de nouvelles fonctionnalités et des intégrations avec des services tiers.

Méthode associée : Créer une application pour la barre d'outils de développement

Configuration d’une intégration d’applications pour la barre d’outils

Les intégrations peuvent ajouter des applications à la barre d’outils de développement dans le hook astro:config:setup.

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

`addDevToolbarApp()`

Type : (entrypoint: DevToolbarAppEntry) => void

Ajouté à la version : astro@4.0.0

Une fonction disponible pour le hook astro:config:setup qui ajoute des applications à la barre d’outils de développement. Elle accepte un objet avec les propriétés requises suivantes pour définir l’application de barre d’outils : id, name et entrypoint. En option, vous pouvez également définir une icône pour votre application.

`id`

Type : string

Un identifiant unique pour l’application. Il sera utilisé pour identifier l’application de manière unique dans les hooks et les événements.

{
  id: 'mon-appli',
  // ...
}

`name`

Type : string

Le nom de l’application. Il sera affiché aux utilisateurs chaque fois que l’application devra être référencée à l’aide d’un nom lisible par l’humain.

{
  // ...
  name: 'Mon appli',
  // ...
}

`icon`

Type : Icon | string
Par défaut : "?"

L’icône utilisée pour afficher l’application dans la barre d’outils. Il peut s’agir d’une icône de la liste des icônes, ou d’une chaîne de caractères contenant le balisage SVG de l’icône.

{
  // ...
  icon: '<svg>...</svg>', // ou, par exemple, 'astro:logo'
  // ...
}

`entrypoint`

Type : string | URL

Chemin d’accès au fichier qui exporte l’application de la barre d’outils de développement.

{
  // ...
  entrypoint: './mon-appli.js',
}

Ajouté à la version : astro@5.0.0

La fonction accepte également une URL comme point d’entrée (entrypoint) :

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "mon-integration",
  hooks: {
    "astro:config:setup": ({ addDevToolbarApp }) => {
      addDevToolbarApp({
        id: "mon-appli",
        name: "Mon Appli",
        icon: "<svg>...</svg>",
        entrypoint: new URL("./mon-appli.js", import.meta.url),
      });
    },
  },
});

Structure d’une application pour la barre d’outils de développement

Une application de barre d’outils de développement est un fichier .js ou .ts qui exporte par défaut un objet en utilisant la fonction defineToolbarApp() disponible dans le module astro/toolbar.

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;
  }
});

`defineToolbarApp()`

Type : (app: DevToolbarApp) => DevToolbarApp

Ajouté à la version : astro@4.7.0

Une fonction qui définit la logique de votre application de barre d’outils lorsqu’elle est chargée et désactivée.

Cette fonction prend un objet avec une fonction init() qui sera appelée lorsque l’application de la barre d’outils sera chargée. Elle peut également prendre une fonction beforeTogglingOff() qui s’exécutera lorsque l’application de la barre d’outils sera cliquée pour désactiver son statut actif.

`init()`

Type : (canvas: ShadowRoot, app: ToolbarAppEventTarget, server: ToolbarServerHelpers) => void | Promise<void>

Bien que cela ne soit pas obligatoire, la plupart des applications utiliseront cette fonction pour définir le comportement de base de l’application. Cette fonction ne sera appelée qu’une seule fois lors du chargement de l’application, soit lorsque le navigateur est inactif, soit lorsque l’utilisateur clique sur l’application dans l’interface utilisateur, selon ce qui se produit en premier.

La fonction reçoit trois arguments pour définir la logique de votre application : canvas (pour afficher les éléments à l’écran), app (pour envoyer et recevoir des événements côté client depuis la barre d’outils de développement), et server (pour communiquer avec le serveur).

`canvas`

Type : ShadowRoot

Une interface ShadowRoot standard que l’application peut utiliser pour afficher son interface utilisateur. Les éléments peuvent être créés et ajoutés au ShadowRoot à l’aide des API DOM standard.

Chaque application reçoit son propre ShadowRoot dédié pour le rendu de son interface utilisateur. De plus, l’élément parent est positionné en utilisant position: absolute; afin que l’interface utilisateur de l’application n’affecte pas la mise en page d’une page Astro.

export default defineToolbarApp({
  init(canvas) {
    canvas.appendChild(document.createTextNode('Hello World!'))
  }
});

`app`

Type : ToolbarAppEventTarget

Ajouté à la version : astro@4.7.0

Une interface EventTarget standard avec quelques aides supplémentaires pour les événements côté client qui peuvent être utilisées pour envoyer et recevoir des événements depuis la barre d’outils de développement.

export default defineToolbarApp({
  init(canvas, app) {
    app.onToggled(({ state }) => {
      const text = document.createTextNode(
        `Cette application est ${state ? "activée" : "désactivée"} !`,
      );
      canvas.appendChild(text);
    });
  },
});

`server`

Type : ToolbarServerHelpers

Ajouté à la version : astro@4.7.0

Un objet qui peut être utilisé pour communiquer avec le serveur.

export default defineToolbarApp({
  init(canvas, app, server) {
    server.send('mon-message', { message: 'Bonjour !' });

    server.on('message-du-serveur', (data) => {
      console.log(data.message);
    });
  },
});

`beforeTogglingOff()`

Type : (canvas: ShadowRoot) => boolean | Promise<boolean>

Ajouté à la version : astro@4.7.0

Cette fonction facultative est appelée lorsque l’utilisateur clique sur l’icône de l’application dans l’interface utilisateur pour la désactiver. Cette fonction peut être utilisée, par exemple, pour effectuer des opérations de nettoyage ou pour demander à l’utilisateur une confirmation avant de désactiver l’application.

Si une valeur fausse est renvoyée, la désactivation sera annulée et l’application restera activée.

export default defineToolbarApp({
  // ...
  beforeTogglingOff() {
    const confirmation = window.confirm('Êtes-vous sûr de vouloir désactiver cette application ?');
    return confirmation;
  }
});

canvas

Type : ShadowRoot

Le ShadowRoot de l’application, peut être utilisé pour afficher toute interface utilisateur nécessaire avant la fermeture. Identique à l’argument canvas de la fonction init.

Événements côté client

En plus des méthodes standards d’une interface EventTarget (addEventListener, dispatchEvent, removeEventListener, etc.), l’objet app possède aussi les méthodes suivantes :

`onToggled()`

Type : (callback: (options: {state: boolean})) => void

Ajouté à la version : astro@4.7.0

Enregistre une fonction de rappel à exécuter lorsque l’utilisateur clique sur l’icône de l’application dans l’interface utilisateur pour activer ou désactiver l’application.

app.onToggled((options) => {
  console.log(`L'application est maintenant ${options.state ? 'activée' : 'désactivée'} !`);
});

`onToolbarPlacementUpdated()`

Type : (callback: (options: {placement: 'bottom-left' | 'bottom-center' | 'bottom-right'})) => void

Ajouté à la version : astro@4.7.0

Cet événement est déclenché lorsque l’utilisateur modifie l’emplacement de la barre d’outils de développement. Il peut, par exemple, être utilisé pour repositionner l’interface utilisateur de l’application lorsque la barre d’outils est déplacée.

app.onToolbarPlacementUpdated((options) => {
  console.log(`La barre d'outils est maintenant placée à ${options.placement}!`);
});

`toggleState()`

Type : (options: {state: boolean}) => void

Ajouté à la version : astro@4.7.0

Modifie l’état de l’application. Cela peut être utilisé pour activer ou désactiver l’application de manière programmatique, par exemple, lorsque l’utilisateur clique sur un bouton dans l’interface utilisateur de l’application.

app.toggleState({ state: false });

`toggleNotification()`

Type : (options: {state?: boolean, level?: 'error' | 'warning' | 'info'}) => void

Ajouté à la version : astro@4.7.0

Permet d’afficher une notification sur l’icône de l’application. Elle peut être utilisée pour informer l’utilisateur que l’application requiert son attention ou pour supprimer la notification en cours.

app.toggleNotification({
  state: true,
  level: 'warning',
});

`state`

Type : boolean

Indique si l’application dispose ou non d’une notification pour l’utilisateur. Lorsque la valeur est true, l’icône de l’application sera mise en évidence. À l’inverse, lorsque la valeur est false, la mise en évidence sera supprimée. Si cette propriété n’est pas spécifiée, la valeur true sera supposée.

`level`

Type : 'error' | 'warning' | 'info'
Par défaut : 'error'

Indique le niveau de la notification. Il sera utilisé pour déterminer la couleur et la forme (cercle rose foncé, triangle doré ou carré bleu) de la mise en évidence sur l’icône de l’application. Si cette propriété n’est pas spécifiée, la valeur 'error' sera supposée.

Communication client-serveur

En utilisant les méthodes de Vite pour la communication client-serveur, les applications de la barre d’outils de développement et le serveur peuvent communiquer entre eux. Afin de faciliter l’envoi et la réception de messages personnalisés, des méthodes d’aide sont fournies pour être utilisées à la fois dans votre application de barre d’outils (sur le client) et dans votre intégration (sur le serveur).

Sur le client

Dans votre application, utilisez l’objet server dans le hook init() pour envoyer et recevoir des messages vers et depuis le serveur.

export default defineToolbarApp({
  init(canvas, app, server) {
    server.send('mon-message', { message: 'Bonjour !' });

    server.on('message-du-serveur', (data) => {
      console.log(data.message);
    });
  },
});

`send()`

Type : <T>(event: string, payload: T) => void

Ajouté à la version : astro@4.7.0

Envoie des données au serveur à partir de la logique définie dans l’application de la barre d’outils.

init(canvas, app, server) {
  server.send('mon-appli:mon-message', { message: 'Bonjour !' });
}

Lors de l’envoi de messages du client au serveur, il est conseillé de préfixer le nom de l’événement avec l’identifiant de l’application ou d’autres espaces de noms afin d’éviter les conflits avec d’autres applications ou d’autres intégrations qui pourraient être à l’écoute de messages.

`on()`

Type : <T>(event: string, callback: (data: T) => void) => void

Ajouté à la version : astro@4.7.0

Enregistre une fonction de rappel à exécuter lorsque le serveur envoie un message avec l’événement spécifié.

init(canvas, app, server) {
  server.on('message-du-serveur', (data) => {
    console.log(data.message);
  });
}

Sur le serveur

Dans une intégration, telle que l’intégration qui ajoute votre application de barre d’outils, utilisez le hook astro:server:setup pour accéder à l’objet toolbar afin d’envoyer et de recevoir des messages vers et à partir de vos applications.

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

`send()`

Type : <T>(event: string, payload: T) => void

Ajouté à la version : astro@4.7.0

Envoie des données au client.

'astro:server:setup': ({ toolbar }) => {
  toolbar.send('message-du-serveur', { message: 'Bonjour !' });
},

`on()`

Type : <T>(event: string, callback: (data: T) => void) => void

Ajouté à la version : astro@4.7.0

Enregistre une fonction de rappel à exécuter lorsque le client enverra un message avec l’événement spécifié.

'astro:server:setup': ({ toolbar }) => {
  toolbar.on('mon-appli:mon-message', (data) => {
    console.log(data.message);
  });
},

`onAppInitialized()`

Type : (appId: string, callback: () => void) => void

Ajouté à la version : astro@4.7.0

Enregistre une fonction de rappel à exécuter lors de l’initialisation de l’application.

'astro:server:setup': ({ toolbar }) => {
  toolbar.onAppInitialized('mon-appli', () => {
    console.log("L'application est maintenant initialisée !");
  });
},

`onAppToggled()`

Type : (appId: string, callback: (options: {state: boolean}) => void) => void

Ajouté à la version : astro@4.7.0

Enregistre une fonction de rappel à exécuter lorsque l’utilisateur clique sur l’icône de l’application dans l’interface utilisateur pour activer ou désactiver l’application.

'astro:server:setup': ({ toolbar }) => {
  toolbar.onAppToggled('mon-appli', ({ state }) => {
    console.log(`L'application est maintenant ${state ? 'activée' : 'désactivée'} !`);
  });
},

Bibliothèque de composants

La barre d’outils de développement comprend un ensemble de composants web qui peuvent être utilisés pour créer des applications avec une apparence et une convivialité cohérentes.

`astro-dev-toolbar-window`

Affiche une fenêtre.

Le slot du composant sera utilisé comme contenu de la fenêtre.

<astro-dev-toolbar-window>
  <p>Mon contenu</p>
</astro-dev-toolbar-window>

Lors de la création d’une fenêtre à l’aide de JavaScript, le contenu des slots doit être placé à l’intérieur du DOM allégé du composant.

const myWindow = document.createElement('astro-dev-toolbar-window');
const myContent = document.createElement('p');
myContent.textContent = 'Mon contenu';

// utilise appendChild directement sur `window`, et non sur `myWindow.shadowRoot`
myWindow.appendChild(myContent);

`astro-dev-toolbar-button`

Affiche un bouton.

Le slot du composant sera utilisé comme contenu du bouton.

const myButton = document.createElement('astro-dev-toolbar-button');
myButton.textContent = 'Cliquez-moi !';
myButton.buttonStyle = "purple";
myButton.size = "medium";

myButton.addEventListener('click', () => {
  console.log('Cliqué !');
});

`size`

Type : "small" | "medium" | "large"
Par défaut : "small"

La taille du bouton.

`button-style`

Le style du bouton. En utilisant ghost, le bouton lui-même est invisible et seul le contenu du bouton est affiché.

En JavaScript, définissez cette propriété en utilisant la propriété buttonStyle pour éviter tout conflit avec la propriété native style.

`button-border-radius`

Type : "normal" | "rounded"
Par défaut : "normal"

Ajouté à la version : astro@4.8.0

Le rayon de la bordure du bouton. En utilisant rounded, le bouton aura des coins arrondis et un remplissage uniforme sur tous les côtés.

En JavaScript, définissez cette propriété à l’aide de la propriété buttonBorderRadius.

`astro-dev-toolbar-badge`

Affiche un badge.

Le slot du composant sera utilisé comme contenu du badge.

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

`size`

Type : "small" | "large"
Par défaut : "small"

La taille du badge.

`badge-style`

Le style (couleur) du badge.

En JavaScript, définissez cette propriété en utilisant la propriété badgeStyle pour éviter tout conflit avec la propriété native style.

`astro-dev-toolbar-card`

Affiche une carte. Spécifiez un attribut link facultatif pour que la carte agisse comme un élément <a>.

Lors de la création d’une carte à l’aide de JavaScript, une propriété clickAction peut être spécifiée pour que la carte se comporte comme un élément <button>.

Le slot du composant sera utilisé comme contenu de la carte.

<astro-dev-toolbar-card icon="astro:logo" link="https://github.com/withastro/astro/issues/new/choose">Signaler un problème</astro-dev-toolbar-card>

`card-style`

Le style de la carte. La couleur n’est appliquée au bord de la carte qu’au survol.

En JavaScript, définissez cette propriété à l’aide de cardStyle.

`astro-dev-toolbar-toggle`

Affiche un bouton à bascule, agissant comme une case à cocher. Cet élément est en interne une simple enveloppe autour de l’élément natif <input type="checkbox">. L’élément case à cocher est accessible à l’aide de la propriété input.

const toggle = document.createElement('astro-dev-toolbar-toggle');

toggle.input.addEventListener('change', (evt) => {
  console.log(`Le bouton à bascule est maintenant ${evt.currentTarget.checked ? 'activé' : 'désactivé'} !`);
});

`toggle-style`

Le style du bouton à bascule.

En JavaScript, définissez cette propriété à l’aide de la propriété toggleStyle.

`astro-dev-toolbar-radio-checkbox`

Ajouté à la version : astro@4.8.0

Affiche un bouton radio. Similaire au composant astro-dev-toolbar-toggle, cet élément est une simple enveloppe autour d’un élément natif <input type="radio">. L’élément radio est accessible à l’aide de la propriété input.

const radio = document.createElement('astro-dev-toolbar-radio-checkbox');

radio.input.addEventListener('change', (evt) => {
  console.log(`Le bouton radio est maintenant ${evt.currentTarget.checked ? 'activé' : 'désactivé'} !`);
});

`radio-style`

Le style du bouton radio.

En JavaScript, définissez cette propriété à l’aide de la propriété radioStyle.

`astro-dev-toolbar-highlight`

Peut être utilisé pour mettre en évidence un élément sur la page. Dans la plupart des cas, vous souhaiterez positionner et redimensionner cet élément à l’aide des propriétés CSS top, left, width et height pour le faire correspondre à l’élément que vous souhaitez mettre en évidence.

<!-- Mise en évidence de la page entière -->
<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';

`highlight-style`

Le style de la mise en évidence.

`icon`

Une icône à afficher dans le coin supérieur droit de la mise en évidence.

`astro-dev-toolbar-tooltip`

Affiche une infobulle avec différentes sections. Ce composant est défini sur display: none; par défaut et peut être rendu visible en utilisant l’attribut data-show="true".

Les sections sont définies à l’aide de la propriété sections. Cette propriété est un tableau d’objets ayant la forme suivante :

{
  title?: string; // Titre de la section
  inlineTitle?: string; // Titre de la section, affiché sur place à côté du titre
  icon?: Icon; // Icône de la section
  content?: string; // Contenu de la section
  clickAction?: () => void | Promise<void>; // Action à effectuer en cliquant sur la section
  clickDescription?: string; // Description de l'action à effectuer en cliquant sur la section
}

const tooltip = document.createElement('astro-dev-toolbar-tooltip');

tooltip.sections = [{
  title: 'Ma section',
  icon: 'astro:logo',
  content: 'Mon contenu',
  clickAction: () => {
    console.log('Cliqué !')
  },
  clickDescription: 'Cliquez-moi !'
}]

Ce composant est souvent combiné avec le composant astro-dev-toolbar-highlight pour afficher une infobulle au survol d’un élément mis en évidence :

const highlight = document.createElement('astro-dev-toolbar-highlight');

// Positionne la mise en évidence...

const tooltip = document.createElement('astro-dev-toolbar-tooltip');

// Ajoute des sections à l'infobulle...

highlight.addEventListener('mouseover', () => {
  tooltip.dataset.show = 'true';
});

highlight.addEventListener('mouseout', () => {
  tooltip.dataset.show = 'false';
});

`astro-dev-toolbar-icon`

Affiche une icône. Une icône de la liste des icônes peut être spécifiée en utilisant l’attribut icon, ou le balisage SVG d’une icône peut être passé en tant que slot.

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

<astro-dev-toolbar-icon>
  <svg>...</svg>
</astro-dev-toolbar-icon>

`astro-dev-toolbar-select`

Ajouté à la version : astro@4.6.0

Affiche un élément de sélection. Similaire au composant astro-dev-toolbar-toggle, cet élément est une simple enveloppe autour d’un élément natif <select>. Utilisez la propriété element pour accéder à l’élément de sélection.

const mySelect = document.createElement("astro-dev-toolbar-select");
const options = [
  { label: "Première option", value: "premier" },
  { label: "Deuxième option", value: "deuxieme", isDefault: true },
];
const myOptions = options.map((option) => {
  const optionEl = document.createElement("option");
  optionEl.textContent = option.label;
  optionEl.setAttribute("value", option.value);
  optionEl.selected = option.isDefault || false;
  return optionEl;
});

mySelect.selectStyle = "green";
mySelect.append(...myOptions);

mySelect.element.addEventListener("change", (evt) => {
  if (evt.currentTarget instanceof HTMLSelectElement) {
    console.log(`La valeur sélectionnée est maintenant ${evt.currentTarget.value}!`);
  }
});

`select-style`

Le style de l’élément select.

En JavaScript, définissez cette propriété à l’aide de la propriété selectStyle.

Icônes

Les icônes suivantes sont actuellement disponibles et peuvent être utilisées dans tout composant acceptant une icône :

astro:logo
warning
arrow-down
bug
check-circle
gear
lightbulb
file-search
star
checkmark
dots-three
copy
compress
grid
puzzle
approveUser
checkCircle
resizeImage
searchFile
image
robot
sitemap
gauge
person-arms-spread
arrow-left
houston-detective

Toutes les icônes ci-dessus utilisent fill="currentColor" par défaut et héritent de la couleur de l’élément parent.

Contribuer Communauté Parrainer