Composantes Web

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

Avant de commencer

Consultez la page Pour commencer pour en savoir plus sur les façons de travailler avec les codes du Système de conception et pour obtenir un lien vers notre trousse de distribution.

Dans cette page

À propos des composantes Web
Choisir la bonne trousse pour votre projet
Pour commencer
Comment utiliser les composantes
Mises à jour
En savoir plus

À 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;
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 (Node Package Manager).

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 quatre trousses regroupant différents éléments :

des jetons de conception;
des styles globaux;
une bibliothèque de composantes;
et une bibliothèque de composantes 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.

Jetons de conception

La trousse de jetons de conception comprend tous les jetons de conception représentant les valeurs brutes employées dans l’ensemble du Système de conception, par exemple les couleurs, les polices, ainsi que les éléments et les plans génériques.

Cet outil est la trousse NPM de base du Système de conception pour l’Ontario et vous pouvez aussi vous en servir pour accéder directement aux jetons de conception dans les projets pour lesquels vous ne voulez pas utiliser la trousse de styles globaux.

Styles globaux

La trousse de styles globaux est indispensable lorsqu’on utilise les composantes du Système de conception pour l’Ontario.

Elle renferme les styles globaux du Système de conception pour l’Ontario qui sont employés pour les éléments et les plans plus génériques, ainsi qu’une série de polices.

Bibliothèque de composantes

La bibliothèque de composantes 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 pour React

La bibliothèque de composantes 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.

Component Library

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

Installer la trousse NPM.

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

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>

Les composantes peuvent ensuite être utilisées comme éléments HTML dans votre site.
```
<ontario-button type="primary">Click me!</ontario-button>
```

Bibliothèque de composantes pour React

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

Installer la trousse NPM.

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

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

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

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 React.

Les ressources que contient la trousse NPM se trouvent à @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, et ce, avec n’importe quel système d’exploitation :

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

Conseil : Si vous utilisez un fichier package.json, ajoutez un script pour simplifier la mise à jour des ressources.

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 sur les composantes

Télécharger la documentation développeur sur les composantes (fichier compressé - anglais seulement) pour des conseils sur l’usage de chaque composante.

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>

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

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

Bibliothèque de composantes 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)

Pour nous joindre

Si vous avez des questions ou souhaitez donner de la rétroaction, veuillez communiquer avec nous.