Structure de la section plugin.platforms

Le fichier pubspec.yaml est le manifeste essentiel de tout plugin Flutter. Il détaille au framework les plateformes prises en charge, les classes d'entrée spécifiques à chaque environnement natif, et les dépendances requises. Pour qu'un plugin Flutter puisse fonctionner sur OpenHarmony, il est impératif d'y ajouter une déclaration spécifique pour cette plateforme. Bien que cette configuration semble directe, elle recèle des subtilités qu'il est crucial de maîtriser pour une intégration réussie sur plusieurs systèmes d'exploitation.

Exemple de configuraton pour un plugin de reconnaissance vocale

Voici un extrait de la section flutter: plugin: platforms: d'un pubspec.yaml, illustrant la configuration pour différentes plateformes, y compris OpenHarmony.

flutter:
  plugin:
    platforms:
      android:
        package: bz.rxla.flutter.speechrecognition
        pluginClass: FlutterSpeechRecognitionPlugin
      ios:
        pluginClass: FlutterSpeechRecognitionPlugin
      macos:
        pluginClass: FlutterSpeechRecognitionPlugin
      ohos:
        package: com.flutter.speech_recognition
        pluginClass: FlutterSpeechPlugin

Description des champs clés

Chaque entrée de plateforme sous platforms utilise des champs spécifiques pour guider le framework Flutter. Voici les plus importants :

Champ	Description	Requis
platforms	Liste des plateformes supportées par le plugin.	Oui (contient les plateformes spécifiques)
package	Nom du paquet ou du module natif.	Obligatoire pour Android et ohos.
pluginClass	Nom de la classe d'entrée du plugin côté natif.	Oui

Différences de configuration par plateforme

La nécessité des champs package et pluginClass peut varier selon la plateforme :

Plateforme	Nécessite package	pluginClass	Justification
android	Oui	FlutterSpeechRecognitionPlugin	Utilise le nom de paquet Java pour localiser la classe.
ios	Non	FlutterSpeechRecognitionPlugin	Objective-C ne gère pas les noms de paquets de la même manière.
macos	Non	FlutterSpeechRecognitionPlugin	Similaire à iOS.
ohos	Oui	FlutterSpeechPlugin	Le nom du module ArkTS est utilisé pour identifier la classe.

Le champ package pour OpenHarmony (ohos)

Pour la plateforme ohos, le champ package est essentiel :

ohos:
  package: com.flutter.speech_recognition
  pluginClass: FlutterSpeechPlugin

Le champ package doit correspondre au nom du module défini dans le fichier oh-package.json5 du projet OpenHarmony. C'est via ce nom que le framework Flutter-OHOS localise le code natif du plugin. Quant au pluginClass, il fait référence à la classe principale exportée dans le fichier index.ets du module OpenHarmony.

// ohos/src/main/ets/components/plugin/index.ets
export { FlutterSpeechPlugin } from './FlutterSpeechPlugin';

Considérations sur le nommage de pluginClass

Il est important que le pluginClass corresponde précisément à la classe native d'entrée pour chaque plateforme :

Plateforme	pluginClass	Remarques
android	FlutterSpeechRecognitionPlugin	Doit correspondre au nom de la classe Java.
ios	FlutterSpeechRecognitionPlugin	Doit correspondre au nom de la classse Objective-C.
ohos	FlutterSpeechPlugin	Doit correspondre au nom de la classe exportée en ArkTS.

Il est tout à fait acceptable que le pluginClass diffère entre les plateformes. Par exemple, pour OpenHarmony, un nom tel que FlutterSpeechPlugin peut être utilisé, même si Android utilise FlutterSpeechRecognitionPlugin. Cette divergence est souvent due au fait que l'implémentation pour OpenHarmony peut être entièrement nouvelle, et non une simple traduction du code Android, justifiant ainsi un nommage plus concis ou spécifique à la plateforme.

Association des déclarations package et pluginClass pour OpenHarmony

Lien entre package de pubspec.yaml et oh-package.json5

La cohérence est primordiale pour que le plugin soit correctement identifié et compilé sur OpenHarmony.

# pubspec.yaml
ohos:
  package: com.flutter.speech_recognition

// ohos/oh-package.json5
{
  "name": "com.flutter.speech_recognition",
  "version": "1.0.0",
  // ...
}

Les noms spécifiés dans pubspec.yaml et oh-package.json5 doivent être **rigoureusement identiques**. Le framework Flutter-OHOS s'appuie sur le nom du package défini dans pubspec.yaml pour localiser le module OpenHarmony correspondant durant la compilation.

Lien entre pluginClass et index.ets

Le pluginClass défini dans pubspec.yaml doit pointer vers la classe d'entrée correcte en ArkTS.

# pubspec.yaml
ohos:
  pluginClass: FlutterSpeechPlugin

// ohos/src/main/ets/components/plugin/index.ets
export { FlutterSpeechPlugin } from './FlutterSpeechPlugin';

Le framework Flutter-OHOS importe la classe désignée par pluginClass depuis le fichier index.ets et l'enregistre automatiquement au démarrage du moteur.

Erreurs de configuration fréquentes

Les problèmes les plus courants sont liés à des incohérences de nommage ou à l'oubli de déclarations essentielles :

Erreur fréquente	Symptôme	Solution
Nom de package non concordant	Le plugin est introuvable à la compilation.	Assurer l'exacte correspondance entre pubspec.yaml et oh-package.json5.
Nom de pluginClass non concordant	Le plugin n'est pas enregistré à l'exécution.	S'assurer que le nom correspond à la classe exportée dans index.ets.
Déclaration ohos manquante	MissingPluginException sur OpenHarmony.	Ajouter la configuration complète pour ohos dans pubspec.yaml.
Erreur de casse ou de typographie dans pluginClass	Erreurs d'exécution ou de chargement.	Vérifier attentivement la casse et l'orthographe.

Stratégie de gestion des versions pour les plugins multiplateformes

Gestion des numéros de version

La version d'un plugin Flutter suit généralement la gestion sémantique des versions (SemVer) :

name: flutter_speech
description: A speech recognition plugin for Flutter
version: 0.3.0+1

Composant	Signification	Exemple
Majeur	Modifications API incompatibles	0 → 1
Mineur	Nouvelles fonctionnalités rétrocompatibles	3
Patch	Corrections de bugs rétrocompatibles	0
Numéro de build	Identifiant de construction interne (optionnel)	+1

Politique de version suite à l'ajout du support OpenHarmony

L'intégration d'une nouvelle plateforme, comme OpenHarmony, est considérée comme l'ajout d'une fonctionnalité rétrocompatible. Conformément à la gestion sémantique des versions (SemVer), cela justifie d'incrémenter le **numéro de version mineure** :

# Avant l'ajout d'OpenHarmony
version: 0.3.0

# Après l'ajout d'OpenHarmony
version: 0.4.0

Différences fonctionnelles spécifiques à la plateforme

Si des limitations spécifiques à une plateforme existent, par exemple, si OpenHarmony ne prend en charge que la reconnaissance vocale en chinois, il est crucial de documenter clairement cette restriction dans les fichiers README et CHANGELOG :

## 0.4.0
- Ajout du support de la plateforme OpenHarmony
- Note : OpenHarmony ne prend actuellement en charge que la reconnaissance vocale en chinois (zh_CN)

Rétrocompatibilité

L'ajout du support OpenHarmony à un plugin ne devrait pas affecter les utilisateurs existants sur Android, iOS ou macOS. Cela signifie que :

• Les fichiers pubspec.yaml des applications existantes n'ont pas besoin d'être modifiés.
• L'API Dart publique du plugin reste inchangée.
• Le code natif spécifique à OpenHarmony ne sera utilisé que lorsque l'application sera exécutée sur un appareil OpenHarmony.

Contraintes d'environnement : Versions SDK et Flutter requises

Configuration actuelle

La section environment spécifie les versions minimales et maximales du SDK Dart et de Flutter avec lesquelles le plugin est compatible :

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: '^3.0.0'

Compatibilité avec le SDK Flutter-OHOS

Le SDK Flutter-OHOS est basé sur des versions spécifiques du SDK Flutter et Dart :

Version Flutter-OHOS	Basée sur Flutter	SDK Dart
3.35.7-dev	Flutter 3.x	Dart 3.x

Recommandations pour les contraintes de version

Pour offrir une plus grande flexibilité et compatibilité avec les futures versions du SDK Flutter-OHOS, il est conseillé d'utiliser un opérateur de versionation tel que >=3.0.0 plutôt que l'opérateur caret ^3.0.0 pour la dépendance Flutter :

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: '>=3.0.0'

Version du SDK OpenHarmony

La version du SDK OpenHarmony est spécifiée dans le fichier oh-package.json5 du module OpenHarmony, et non dans le pubspec.yaml du plugin Flutter :

// ohos/oh-package.json5
{
  "devDependencies": {
    "@ohos/flutter_ohos": "file:../har/flutter_ohos.har"
  }
}

Gestion des dépendances et considérations de publication

Déclaration des dépendances

La section dependencies liste les paquets requis par le plugin. Un plugin comme flutter_speech qui ne dépend que du SDK Flutter, sans autres dépendances tierces, est un exemple de bonne pratique. La réduction des dépendances minimise les risques de conflits de versions et simplifie la maintenance.

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter

Publication sur pub.dev

Si vous envisagez de publier votre plugin sur pub.dev :

1. Actuellement, pub.dev ne prend **pas en charge** la validation des configurations spécifiques à la plateforme OpenHarmony.
2. Cependant, la présence de la configuration ohos dans votre pubspec.yaml n'affectera pas la publication. pub.dev ignorera simplement les plateformes qu'il ne reconnaît pas.
3. Il est essentiel de s'assurer que le code pour les plateformes prises en charge par pub.dev (comme Android et iOS) est entièrement fonctionnel et conforme aux exigences.

Publication dans l'écosystème OpenHarmony (par exemple, Gitcode)

La communauté OpenHarmony dispose de ses propres plateformes de gestion de paquets. Lors de la publication pour cet écosystème, il est nécessaire de :

1. Vérifier la validité et l'exactitude du fichier oh-package.json5.
2. Fournir une documentation README complète et claire.
3. Inclure des exemples de code fonctionnels.
4. Réussir les processus de révision et d'approbation de la communauté.

Configuration de .gitignore

Un fichier .gitignore bien configuré est crucial pour exclure les fichiers générés et spécifiques à l'environnement de développement :

# Flutter
.dart_tool/
.packages
build/

# OpenHarmony
ohos/.preview/
ohos/build/
ohos/node_modules/
ohos/.cxx/

Liste de vérification avant publication

Avant de finaliser la publication de votre plugin multiplateforme, assurez-vous de cocher les points suivants :

• Vérifier que toutes les configurations de plateforme dans pubspec.yaml sont correctes.
• Asssurer que le numéro de version a été mis à jour.
• Mettre à jour le fichier CHANGELOG avec les modifications pertinentes.
• Inclure les instructions d'utilisation d'OpenHarmony dans le README.
• Confirmer que les exemples de code fonctionnent sur toutes les plateformes supportées.
• Valider que tous les tests ont été passés avec succès.
• Vérifier que .gitignore exclut tous les artefacts de construction.
• S'assurer de la présence d'un fichier LICENSE.

Exemple complet de pubspec.yaml

Voici un exemple complet et bien structuré d'un fichier pubspec.yaml pour un plugin Flutter prenant en charge OpenHarmony :

name: flutter_speech
description: A speech recognition plugin for Flutter supporting Android, iOS, macOS, and OpenHarmony.
version: 0.4.0
homepage: https://github.com/jaumard/flutter_speech_recognition

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: '>=3.0.0'

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter

flutter:
  plugin:
    platforms:
      android:
        package: bz.rxla.flutter.speechrecognition
        pluginClass: FlutterSpeechRecognitionPlugin
      ios:
        pluginClass: FlutterSpeechRecognitionPlugin
      macos:
        pluginClass: FlutterSpeechRecognitionPlugin
      ohos:
        package: com.flutter.speech_recognition
        pluginClass: FlutterSpeechPlugin

Chaque ligne de ce fichier pubspec.yaml a un rôle précis, garantissant une configuration claire et sans éléments superflus pour la prise en charge multiplateforme.

Cet article a détaillé les aspects fondamentaux de la configuration multiplateforme d'un plugin Flutter, en se concentrant sur le fichier pubspec.yaml et l'intégration d'OpenHarmony. Les points clés abordés incluent :

• La section plugin.platforms, insistant sur la nécessité des champs package et pluginClass pour OpenHarmony.
• L'importance de la cohérence des noms : le package doit correspondre à oh-package.json5 et le pluginClass à la classe exportée dans index.ets.
• La stratégie de versioning, recommandant l'incrémentation du numéro de version mineure lors de l'ajout d'une nouvelle plateforme.
• Les contraintes d'environnement pour assurer la compatibilité avec le SDK Flutter-OHOS.
• Les considérations de publication, notamment le fait que pub.dev ignore la configuration ohos, ce qui n'entrave pas la publication des autres plateformes.