Aller au contenu
Deep Thoughts

Comment créer un indicateur de progression horizontal pour votre site Starlight

Cette traduction a été générée par une IA générative à l'aide de la traduction continue Action. →

A beautiful cover image with the text "Progress Bar"
• 2 min de lecture • 400 mots
Frostybee
Frostybee
 Felix Schneider
Felix Schneider
trueberryless

Dans cet article, nous aimerions vous montrer comment frostybeeFrostyBee a créé un indicateur de progression horizontal et épuré pour les sites Starlight.

Prérequis

Vous devez disposer d’un site web Starlight existant.

Créer le composant d’indicateur de progression

Créons un nouveau composant appelé ProgressIndicator.astro dans le répertoire src/components/. Ce composant sera chargé de rendre l’indicateur de progression.

Nous créons un conteneur qui s’étend sur toute la largeur avec la barre de progression <div> à l’intérieur. La largeur de l’élément <div> interne est mise à jour chaque fois que l’utilisateur fait défiler la page (et lors du chargement de celle-ci) pour refléter la position de défilement actuelle.

src/components/ProgressIndicator.astro
<div class="progress-scroll-container" aria-hidden="true">
  <div id="progress-scroll"></div>
</div>


<script>
  window.addEventListener("scroll", function () {
    updateProgressScroll();
  });
  window.addEventListener("load", function () {
    updateProgressScroll();
  });


  function updateProgressScroll() {
    if (document) {
      const progressScroll = document.getElementById("progress-scroll");
      if (progressScroll) {
        var scrollTop = window.scrollY || document.documentElement.scrollTop;
        var scrollHeight =
          document.documentElement.scrollHeight - window.innerHeight;
        var progress = (scrollTop / scrollHeight) * 100;
        progressScroll.style.width = progress + "%";
      }
    }
  }
</script>


17 collapsed lines
<style>
  html:is(:not([data-has-hero]), [data-has-sidebar], [data-has-toc]) .progress-scroll-container {
    position: fixed;
    top: var(--sl-nav-height);
    left: 0;
    height: 0.25rem;
    width: 100%;
    background-color: transparent;
    z-index: 3;
  }


  #progress-scroll {
    height: 100%;
    width: 0px;
    background-color: var(--sl-color-accent-high);
  }
</style>


<style is:global>
  #starlight__on-this-page--mobile {
    margin-top: 0.25rem;
  }
</style>

Dans les lignes masquées se trouve le style qui s’assure que la barre de progression ressemble à une barre de progression typique. Elle est également adaptée à Starlight car la barre est automatiquement masquée lorsque le site n’a ni barre latérale ni table des matières, mais possède un élément « hero », comme la plupart des pages de destination.

Un point important à noter concernant le CSS global (ligne 45) : il déplace le menu déroulant de la table des matières mobile vers le bas pour créer plus d’espace blanc au niveau de la barre de progression. C’est une préférence personnelle et vous pouvez le supprimer si vous le souhaitez.

Surcharge dans Starlight

Nous pouvons maintenant utiliser ce composant dans une surcharge Starlight. Dans ce cas, il est logique de surcharger le composant Header.astro comme ceci :

src/components/Header.astro
---
import Default from "@astrojs/starlight/components/Header.astro";
import ScrollIndicator from "./ScrollIndicator.astro";
---


<Default><slot /></Default>
<ScrollIndicator />

N’oubliez pas d’ajouter cette surcharge de composant à votre fichier astro.config.mjs :

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs with a Progress Indicator',
      components: {
        // Override the default `Header` component.
        Header: './src/components/Header.astro',
      },
    }),
  ],
});

Code source

Vous pouvez trouver l’intégralité du code du projet sur GitHub et dans cet exemple sur Stackblitz.

Conclusion

Avec cette configuration, l’indicateur de progression sera affiché sur chaque page (sauf les pages de destination) de votre site Starlight. 🥳

Vous pouvez également consulter le plugin Starlight Scroll To Top de FrostyBee, qui prend également en charge un Progress Ring intégré depuis la version 0.3.1. 🙌

Étiquettes :