Composantes Web

Découvrez les composantes Web et apprenez comment utiliser la bibliothèque de composantes du Système de conception dans votre application.

À propos des composantes Web

Les composantes Web sont un ensemble d’interfaces de programmation (API) employées sur une plateforme pour créer des balises HTML personnalisées, encapsulées et réutilisables dans les pages et les applications Web. Elles permettent de gérer au même endroit la logique, les styles et la disposition propre à certaines composantes.

Elles sont utilisées sensiblement de la même façon que les autres éléments HTML, tels que <input> ou <button>, qui forment les blocs de construction du Web.

Les composantes Web sont proposées en tant que bibliothèque et réparties en deux trousses :

• la bibliothèque de composantes primaires, à utiliser avec le langage HTML ou n’importe quelle structure;
• une trousse spéciale à utiliser dans les applications Angular;
• et une trousse spéciale à utiliser dans les applications React.

Nous comptons intégrer d’autres structures JavaScript dans le futur.

Trousses

Les composantes Web du Système de conception pour l’Ontario sont développées au moyen d’une chaîne d’outils appelée Stencil et sont accessibles dans les trousses npm (npm).

L’utilisation de npm permet à notre équipe de créer, de mettre à jour et de publier des composantes versionnées et cohérentes pour tous les usages de la bibliothèque de composantes Web.

Choisir la bonne trousse pour votre projet

Le Système de conception pour l’Ontario propose 3 trousses regroupant différents éléments :

• Bibliothèque de composantes Web;
• Bibliothèque de composantes Web pour Angular;
• et Bibliothèque de composantes Web pour React.

La plupart des développeurs voudront choisir la bibliothèque de composantes ou la bibliothèque de composantes pour React, selon leurs besoins. Par exemple, si vous utilisez React, choisissez la bibliothèque de composantes pour React.

Toutes les trousses du Système de conception pour l’Ontario.

Bibliothèque de composantes Web

La trousse Bibliothèque de composantes Web contient toutes les composantes Web disponibles dans le Système de conception pour l’Ontario qui peuvent être utilisées partout où il y a du langage HTML ou JavaScript.

Elle contient une série d’éléments qui peuvent être copiés et utilisés pour votre projet, par exemple des logos.

Utilisez cette trousse si vous travaillez avec un langage HTML simple ou avec une structure ou un outillage qui n’utilise pas React.

Bibliothèque de composantes Web pour Angular

La trousse Bibliothèque de composantes Web pour Angular contient les mêmes éléments que la bibliothèque de composantes, sauf que ces éléments sont conçus à l’origine pour être utilisés avec Angular.

La trousse renferme également une série d’éléments qui peuvent être copiés et utilisés pour votre projet, par exemple des logos.

Utilisez cette trousse si vous travaillez avec Angular pour créer votre application. Prend en charge Angular 12 et les versions ultérieures.

Bibliothèque de composantes Web pour React

La trousse Bibliothèque de composantesa Web pour React contient les mêmes éléments que la bibliothèque de composantes, sauf qu’ils sont conçus à l’origine pour être utilisés avec React.

Elle renferme également une série d’éléments qui peuvent être copiés et utilisés pour votre projet, par exemple des logos.

Utilisez cette trousse si vous travaillez avec React pour créer votre application, y compris avec des chaînes d’outils telles que Gatsby ou NextJS.

Pour commencer

Tout d’abord, choisissez la bonne trousse pour votre projet et sachez exactement celle que vous voulez utiliser.

Bibliothèque de composantes Web

Suivez ces étapes pour importer la bibliothèque de composantes dans votre projet :

1. Installer la trousse npm.

   npm install --save @ontario-digital-service/ontario-design-system-component-library-react

2. Ajouter les étiquettes suivantes à votre commande HTML pour importer la bibliothèque de composantes.

   <script type="module" src="dist/ontario-design-system-components/ontario-design-system-components.esm.js"></script>
   <script nomodule src="dist/ontario-design-system-components/ontario-design-system-components.js"></script>

3. Les composantes peuvent ensuite être utilisées comme éléments HTML dans votre site.

   <ontario-button type="primary">Click me!</ontario-button>

"clean:ontario-ds": "rm -rf components/vendor/ontario-ds",
"copy:ontario-ds": "npm run clean:vendor && copyfiles -u 3 \"node_modules/@ontario-digital-service/ontario-design-system-component-library/dist/**\" components/vendor/ontario-ds"

Bibliothèque de composantes Web pour Angular

Suivez ces étapes pour importer la bibliothèque de composantes pour Angular dans un projet Angular :

1. Installer la trousse npm.

   npm install --save @ontario-digital-service/ontario-design-system-component-library-angular

2. Importez ComponentLibraryModule, ou toute autre composante particulière que vous souhaitez utiliser, dans votre module racine. Le module ComponentLibraryModule importé comprendra toutes les composantes Web du Système de conception pour l’Ontario.

   importer { ComponentLibraryModule } de '@ontario-digital-service/ontario-design-system-component-library-angular/dist/component-library';
   
   @NgModule({
       Importe : [ComponentLibraryModule],
   })
   export class AppModule {}

3. Les composantes peuvent ensuite être utilisées comme des composantes Angular ordinaires.

   <ontario-button type="primary">Primary Button</ontario-button>

Bibliothèque de composantes Web pour React

Suivez ces étapes pour importer la bibliothèque de composantes pour React dans un projet React :

1. Installer la trousse npm.

   npm install --save @ontario-digital-service/ontario-design-system-component-library-react

2. Importer les composantes désirées de la bibliothèque de composantes.

   import { OntarioButton } from '@ontario-digital-service/ontario-design-system-component-library-react';

3. Les composantes peuvent ensuite être utilisées comme composantes React standard.

   <OntarioButton type="primary">Click me!</OntarioButton>

Ressources locales

Comme les composantes, les ressources locales (logos, polices, etc.) doivent être copiées dans votre projet pour pouvoir être regroupées lors de la construction de votre application Angular ou React.

Les ressources que contient la trousse npm se trouvent à @ontario-digital-service/ontario-design-system-component-library-angular/dist/assets ou @ontario-digital-service/ontario-design-system-component-library-react/dist/assets, et devraient être copiées dans le répertoire où vous conservez vos ressources publiques.

Dans une application React standard, cela peut être fait de différentes façons. Par exemple, vous pouvez utiliser la trousse npm copyfiles (anglais seulement), et ce, avec n’importe quel système d’exploitation :

Angular

copyfiles -E -f "node_modules/@ontario-digital-service/ontario-design-system-component-library-angular/dist/assets/*" src/assets

React

copyfiles -E -f "node_modules/@ontario-digital-service/ontario-design-system-component-library-react/dist/assets/*" public/assets

"prebuild": "npm run copy:assets",
"copy:images": "copyfiles -E -f \"node_modules/@ontario-digital-service/ontario-design-system-component-library-angular/dist/component-library/assets/images/**\" src/assets",
"copy:favicons": "copyfiles -E -f \"node_modules/@ontario-digital-service/ontario-design-system-component-library-angular/dist/component-library/assets/favicons/**\" src/assets/favicons",
"copy:fonts": "copyfiles -E -u 6 \"node_modules/@ontario-digital-service/ontario-design-system-component-library-angular/dist/component-library/assets/fonts/**/*\" src/assets/fonts",
"copy:assets": "npm run copy:images && npm run copy:favicons && npm run copy:fonts"

Comment utiliser les composantes

Chaque composante est un riche objet JavaScript. Les composantes réagissent et se comportent comme les éléments HTML ordinaires, mais ont la capacité de définir leur propre comportement et leur propre disposition.

Lorsqu’elles sont appliquées, les composantes utilisent un double de DOM pour maintenir leur encapsulage, gérant elles-mêmes leurs styles et leur code.

L’environnement dans lequel les composantes sont utilisées déterminera la syntaxe appropriée. Cependant, celles-ci sont généralement utilisées comme les éléments HTML standard ou comme les composantes React, avec application de données à chaque composante au moyen d’attributs ou de propriétés, respectivement.

Documentation pour les développeurs

Consultez le site de Documentation des composantes web pour les développeurs (anglais seulement) pour trouver des directives, des exemples et la documentation de l’API pour les composantes web et les trousses des bibliothèques de composantes, y compris les mises en oeuvre Angular et React.

Attributs et propriétés

Les propriétés servent à appliquer des données à la composante, par exemple pour en modifier l’état ou pour configurer des styles.

Application d’attributs au langage HTML

Lorsque les composantes sont utilisées directement dans un langage HTML, les propriétés peuvent être appliquées à chaque composante en tant que séquences au moyen d’attributs HTML.

Les propriétés qui acceptent des objets plutôt que de simples séquences peuvent le faire au moyen d’une chaîne JSON :

<ontario-input name="postal" input-width="7-char-width" caption='{"captionText": "Postal Code", "captionType": "default"}' hint-text="For example, A1A 1A1"></ontario-input>

Application de propriétés au langage HTML avec JavaScript

Il est également possible d’interagir avec les composantes au moyen de JavaScript à l’intérieur du navigateur.

Vous pouvez interroger l’élément et manipuler ses propriétés en utilisant un langage JavaScript standard à l’intérieur de balises <script>.

<ontario-input></ontario-input>
<script>
    const ontarioInputElement = document.querySelector('ontario-input');
    ontarioInputElement.name = 'postal';
    ontarioInputElement.inputWidth = '7-char-width';
    ontarioInputElement.caption = { captionText: 'Postal Code', captionType: 'default' };
    ontarioInputElement.hintText = 'For example, A1A 1A1';
</script>

Utiliser les propriétés dans Angular

Contrairement à HTML, Angular bénéficie d’un environnement JavaScript. Cela facilite le travail avec les composantes.

La version Angular des composantes fonctionne comme les composantes originales d’Angular.

Lorsqu’elle est utilisée dans un éditeur pris en charge, l’information de typage TypeScript est mise à disposition pour vous aider à travailler avec les composantes.

Les propriétés utilisent les types JavaScript appropriés, notamment les chaînes de caractères, les nombres et les objets. Elles peuvent être liées à des données en suivant les conventions d’association de données d’Angular.

Utilisation de propriétés dans React

React, contrairement au langage HTML, a l’avantage d’un environnement entièrement JavaScript. Cela permet de travailler encore plus facilement avec les composantes.

Dans leur version React, les composantes se comportent comme les composantes React d’origine.

Dans un éditeur compatible, vous pouvez utiliser l’information de typage TypeScript pour mieux travailler avec les composantes.

Les propriétés utilisent au besoin des types JavaScript, qui comprennent des chaînes, des chiffres et des objets.

<OntarioButton type="primary">Click Me!</OntarioButton>

Application de styles

Les composantes Web peuvent être modifiées par deux types de styles : les styles internes et les styles externes.

En interne, les composantes ont leurs propres styles, intégrés au sein même de leur double de DOM. Ces styles sont appliqués séparément, sans égard aux styles externes, et ne permettent pas une interaction directe. Ainsi, nous pouvons assurer des composantes de qualité, éprouvées et conformes aux normes du Système de conception.

En externe, les composantes peuvent être stylées et intégrées dans votre application en leur attribuant des styles externes, comme n’importe quel autre élément Web.

<style>
    .footer {
        margin-top: auto;
    }
</style>

<ontario-footer class="footer" …></ontario-footer>

Mises à jour

Nos composantes sont publiées dans leurs nouvelles versions au moyen de npm par versionnage sémantique. Cela permet aux usagers des composantes de savoir de manière précise quelle version de composantes leur projet utilise.

Pour mettre à niveau les composantes lorsqu’une nouvelle version est publiée, exécutez les programmes suivants :

Bibliothèque de composantes Web

npm update @ontario-digital-service/ontario-design-system-component-library

Bibliothèque de composantes Web pour Angular

npm update @ontario-digital-service/ontario-design-system-component-library-angular

Bibliothèque de composantes Web pour React

npm update @ontario-digital-service/ontario-design-system-component-library-react

En savoir plus

Consultez ces ressources pour en savoir davantage sur les composantes Web 

• MDN: composantes Web
• Webcomponents.org: Introduction (en anglais)