Un outil CLI simple qui apporte les symboles de matériaux de Google à vos projets Flutter

Un outil CLI simple qui apporte à Google Symboles matériels à vos projets Flutter. Il génère une police d’icônes et sa classe wrapper à partir d’un seul fichier de configuration.

Motivation

Dans la dernière version de MaterialDesign, Matériel3, Symboles matériels a été introduit à la place de Icônes matérielles. Cependant, Flutter ne prend pas encore officiellement en charge les symboles de matériaux. Bien qu’ils soient être pris en chargeil faudra un certain temps avant d’être intégré à la version stable.

Heureusement, Material Symbols est OSS et toutes les ressources sont disponible sur Github. Vous pouvez également voir une liste des symboles disponibles sur leur site officiel. Vous pouvez incorporer immédiatement des symboles de matériaux dans votre projet Flutter en téléchargeant les fichiers SVG des symboles dont vous avez besoin sur le site Web.

D’autre part, les icônes matérielles sont fournies par le Flutter Framework comme Icons classe et peut être utilisé aussi facilement et en toute sécurité que Icons.home. Comment pouvons-nous obtenir la même chose avec les symboles matériels ? Téléchargez d’abord les SVG, convertissez-les en un fichier de police, puis créez une classe wrapper Dart correspondante, et…. Oui, c’est un processus très fastidieux.

Avec fms (symboles de matériau flottant) vous pouvez générer automatiquement ces fichiers à partir d’un seul fichier de configuration. Il n’est pas nécessaire de télécharger et de gérer les ressources manuellement.

Pourquoi « générer » ?

Pourquoi fms prend-il la peine de générer des fichiers de police au lieu de fournir une classe comme Icons ? Les symboles de matériaux ont plus de 2400 icônes et ils sont tous personnalisables avec 5 paramètres. De plus, chaque paramètre a au moins 2 valeurs possibles. Il est donc évident que le nombre de combinaisons possibles des symboles et des paramètres est énorme. Si nous créons une classe qui fournit toutes les variantes de symboles en tant que variables membres statiques, un énorme fichier de police contenant toutes les données de variante doit être inclus dans le package. C’est peu pratique. Au lieu de cela, fms génère un fichier de police qui contient uniquement la quantité de données dont vous avez besoin.

Indice

Préface

L’une des fonctions principales de ce package est fortement basée sur les packages suivants :

• fantastique
  Un package node.js qui convertit plusieurs fichiers SVG en une seule police d’icône. Il est utilisé pour générer des polices d’icônes à partir de SVG de symboles. Par conséquent, node.js de la version 11 ou ultérieure doit être activé.
• icon_font_generator
  Bibliothèque Wrapper pour Fantasticon’s Dart. Il est utilisé pour générer des classes wrapper de polices d’icônes.

Installer

Vous pouvez installer fms à partir de Pub.dev en utilisant pub commande.

$ flutter pub add --dev fms

Assurez-vous que node.js de la version 11 ou ultérieure est installé.

$ node --version   
v18.12.1

Commencer

1. Écrire un fichier de configuration

   # project_root/my_symbols.yaml
   
   family: MySymbols
   
   output:
     flutter: lib/src/my_symbols.dart
     font: assets/my_symbols.ttf
   
   symbols:
     home: Home
     home_selected:
       name: Home
       fill: true

2. Générer une police Icon et sa classe wrapper

   La commande suivante génère une police d’icône dans assets/my_symbols.ttf et sa classe wrapper dans lib/src/my_symbols.dart.

   $ flutter pub run fms build my_symbols.yaml

3. Ajoutez la police d’icônes générée à votre projet Flutter

   Ajouter les informations de la police générée à pubspec.yaml afin que Flutter puisse l’utiliser. N’oubliez pas d’ajouter également le fichier de police à vos actifs dans le assets: section si vous les mettez ailleurs que lib/ (par exemple assets/).

   ...
   
   flutter:
     assets:
       - assets/
     fonts:
       - family: MySymbols
         fonts:
           - asset: assets/my_symbols.ttf

4. Utiliser les icônes générées

   Vous pouvez utiliser les icônes dans le code Dart via MySymbols classe qui est définie dans généré my_symbols.dart.

   import 'package:your_package/src/my_symbols.dart';
   import 'package:flutter/material.dart';
   
   Widget homeNaviDest() {
     return NavigationDestination({
       icon: const Icon(MySymbols.home),
       selectedIcon: const Icon(MySymbols.home_selected),
     });
   }

Comment utiliser

Syntaxe du fichier de configuration

Un fichier de configuration est écrit en YAML. Un fichier de configuration correspond respectivement à une police d’icône et à sa classe wrapper.

Un fichier de configuration se compose des quatre sections suivantes :

family: ... # Family name
output: ... # Output destinations
symbols: ... # Define symbol instances
default: ... # Overrides default parameters（optional）

Nom de famille

Dans family: spécifiez le nom de famille d’une police d’icônes à générer.

Ceci est également utilisé comme nom de la classe wrapper, il doit donc s’agir d’un identifiant approprié dans Dart (généralement UpperCamelCase). Par conséquent, les noms commençant par un chiffre ou contenant des caractères spéciaux ou des espaces ne peuvent pas être utilisés, comme indiqué ci-dessous :

• 10Symbols
• MySymbols#1
• My Symbols

Destinations de sortie

Les destinations de sortie pour une police d’icônes générée et sa classe wrapper sont spécifiées dans output: section.

output:
  flutter: lib/src/my_symbols.dart # Wrapper class
  font: assets/my_symbols.ttf # Icon font

Définir des instances de symbole

Dans symbols: section, vous pouvez définir des instances de symbole : les instances des symboles que vous souhaitez utiliser. Une instance de symbole est un ensemble du nom d’un symbole et de ses paramètres. Chaque instance possède également un identifiant unique au sein de la famille.

• Nom du symbole

  Chaque symbole a un nom unique (par exemple Home, Calendar Month). Les noms de symboles disponibles se trouvent dans le site officiel de la galerie. Faites attention à la casse, aux espaces blancs, etc. (par exemple calendarMonth est faux, Calendar Month est correct).

• Paramètres

  Les symboles de matériaux sont polices variables. Chaque symbole peut être personnalisé en ajustant cinq paramètres. Voir le site officiel pour voir comment chaque paramètre fonctionne.

• Identifiant

  Chaque instance possède également un identifiant unique dans sa famille. Ce sera le nom de la variable de la classe wrapper générée, il doit donc s’agir d’un identifiant approprié pour Dart. fms prend en charge à la fois snake_case et lowerCamelCase, mais les deux styles ne peuvent pas être mélangés dans une famille.

Commençons par un exemple simple. L’extrait de code suivant définit une instance de Home symbole et nommez-le comme home. Le nom du symbole est spécifié dans le name: section.

symbols:
  home: # Identifier
    name: Home # Symbol name

Ensuite, personnalisez les symboles avec des paramètres. Material Symbols prend en charge cinq paramètres : style, axe de poids, axe de remplissage, axe de penteet axe de taille optique.

symbols:
  home:
    name: Home
    style: outlined # style
    weight: 400 # weight axis
    fill: false # fill axis
    grade:  # grade axis
    size: 48px # optical-size axis

Les valeurs possibles pour chaque section de paramètre sont les suivantes :

Tous les paramètres sont facultatifs et peuvent être omis. Les paramètres dont la valeur n’est pas spécifiée auront les valeurs par défaut. Les valeurs par défaut sont style: outlined、weight: 400、fill: false、grade: 0、size: 48px, respectivement. Voici un exemple de création de deux Home symboles (home et home_selected) à utiliser pour les onglets de Barre de navigation.

symbols:
  home: # Equivalent to "fill: false"
    name: Home
  home_selected:
    name: Home
    fill: true

Les name: section peut également être omise si aucun des paramètres n’est spécifié. Dans ce cas, l’identifiant et le nom du symbole doivent être écrits au format clé-valeur. L’exemple ci-dessus peut être réécrit sous forme abrégée comme suit :

symbols:
  home: Home # "name:" section is ommited
  home_selected:
    name: Home
    fill: true

Remplace les paramètres par défaut

Utiliser default: section pour remplacer la valeur par défaut de chaque paramètre. Les valeurs spécifiées ici seront utilisées comme nouveaux paramètres par défaut. Par exemple, pour changer la valeur par défaut de style de outlined pour rounded et la valeur par défaut de weight axis à partir de 400 pour 500écrivez ce qui suit.

default:
  style: rounded
  weight: 500

Les default: La section est facultative et peut être omise.

Commandes

fms a 2 sous-commandes : build et clean.

construire

Utiliser build pour générer une police d’icônes et sa classe wrapper à partir d’un fichier de configuration. Node.js est requis pour que la commande fonctionne. Si vous ne l’avez pas, veuillez d’abord l’installer.

$ flutter pub run fms build your_config_file.yaml

Les options disponibles sont :

• --prefer-camel-case.

  Utilisez lowerCamelCase pour les identifiants des instances de symbole au lieu de snake_case.

• -f, --force.

  Téléchargez les fichiers de ressources même si le cache est disponible.

• --use-yarn.

  Utiliser yarn en tant que gestionnaire de packages node.js au lieu de npm.

Générer plusieurs polices d’icônes

Un fichier de configuration correspond respectivement à une police d’icône et à sa classe wrapper. Si vous souhaitez générer plusieurs polices d’icônes, écrivez également plusieurs fichiers de configuration. Assurez-vous que les noms de famille doivent être uniques dans votre projet.

Vous pouvez transmettre plusieurs fichiers de configuration à la commande build`, il n’est donc pas nécessaire d’appeler la commande plusieurs fois.

$ flutter pub run fms first_symbols.yaml second_symbols.yaml

propre

Les fichiers SVG téléchargés sont mis en cache dans <project_root>/.dart_tool/. Utilisez le clean pour les supprimer.

$ flutter pub run fms clean

Contribution

Tout type de contribution est la bienvenue. Des suggestions pour mon anglais sont également utiles pour améliorer la qualité du document.

GitHub

Voir Github