2026 HarmonyOS PC : que vérifier avant de migrer les modules natifs d’Electron ?
La documentation d’Electron précise que les modules natifs dépendent de l’environnement d’exécution et de l’ABI pour lesquels ils sont construits : ils ne sont donc pas des composants transportables tels quels vers HarmonyOS PC (guide Electron sur les modules Node.js natifs). Pour la migration d’Electron vers HarmonyOS PC, le choix prudent est de conserver les règles métier, de séparer les interfaces de plateforme, puis de ne réécrire en C/C++ que les capacités documentées et validées avec le SDK cible.
Cet article s’adresse aux architectes Electron qui doivent chiffrer les dépendances natives et choisir les premiers modules à traiter.
Il concerne aussi les équipes de développement multiplateforme qui veulent éviter de transposer leurs hypothèses Windows, Linux ou Node.js sans vérification.
Les responsables techniques y trouveront une démarche de cadrage, des critères de report et des contrôles d’acceptation.
Dernière mise à jour : 15 octobre 2026. Vérification fondée sur l’entrée de développement HarmonyOS pour ordinateur, les documents ArkTS Runtime et Node-API disponibles à cette date ; les interfaces et permissions doivent être recontrôlées avec le SDK retenu. (Développement d’applications pour ordinateur, présentation d’ArkTS Runtime, guide Node-API)
Étape préalable : établir la frontière entre code métier et plateforme
L’existence d’une entrée officielle pour le développement d’applications HarmonyOS sur ordinateur ne prouve pas que toutes les capacités utilisées par une application de bureau existante sont disponibles sous une forme équivalente. Elle fournit un point de départ pour examiner les outils et documents pertinents, mais la disponibilité d’une API, son nom, ses permissions et son comportement doivent être établis pour la version et l’environnement effectivement ciblés (documentation de développement HarmonyOS pour ordinateur).
La première décision consiste donc à classer chaque dépendance selon sa fonction, plutôt que de chercher à convertir les fichiers ou les noms de modules un par un. Une bibliothèque de règles de validation ou de traitement de données pourra souvent rester dans une couche partagée, si elle ne dépend pas de Node.js ou d’une API système. À l’inverse, un module qui dialogue avec un périphérique, lit un chemin système, consulte une information propre à l’ordinateur ou appelle une bibliothèque dynamique exige une vérification spécifique.
Trois risques rendent une migration directe particulièrement fragile :
- Dépendance à l’environnement d’exécution : le module peut utiliser des interfaces propres à Node.js, à Electron ou à une version précise de leur ABI. Même si son code source est disponible, il ne s’ensuit pas qu’il soit exploitable dans l’environnement cible.
- Dépendance au système d’exploitation : les appels à des bibliothèques, à des fichiers ou à des périphériques peuvent être spécifiques à Windows ou Linux. L’extension
.dllou.sone suffit pas à établir la compatibilité avec HarmonyOS PC. - Différence d’architecture applicative : les processus principal et de rendu d’Electron, leurs canaux IPC et leurs responsabilités ne doivent pas être recopiés mécaniquement dans la structure des composants HarmonyOS.
- Permissions et accès aux ressources : un accès local précédemment réalisé directement peut devoir passer par une interface ou un mécanisme d’autorisation documenté. Les permissions d’autres systèmes ne permettent pas de déduire celles de HarmonyOS PC.
- Travail asynchrone et cycle de vie : un appel natif peut bloquer le fil d’exécution, rendre les rappels imprévisibles ou laisser des ressources ouvertes si l’annulation et la libération ne sont pas conçues.
Au stade initial, classez donc chaque fonction dans l’une de ces catégories : code métier potentiellement partagé, capacité de plateforme à remplacer, ou capacité encore à confirmer auprès de la documentation et du SDK cible. La dernière catégorie doit rester visible dans les estimations et les plans de livraison ; elle ne doit pas être transformée en promesse de compatibilité.
Étape de cadrage : dresser l’inventaire par capacité
Un inventaire utile décrit les échanges et les effets d’un module, pas seulement son nom ou son emplacement dans le dépôt. Pour chaque fonctionnalité native, il faut suivre son chemin depuis l’interface jusqu’à la ressource sollicitée et noter les conditions de réussite comme les échecs.
La liste de contrôle ci-dessous permet de préparer l’examen de l’architecture existante :
- [ ] Identifier l’appelant : interface, processus principal, processus auxiliaire ou autre service.
- [ ] Noter chaque canal IPC utilisé, les paramètres transmis, le résultat attendu et son format.
- [ ] Recenser le paquet natif, ses dépendances C/C++, ses appels à Node.js et les bibliothèques externes requises.
- [ ] Décrire les interactions avec le système : fichiers, caméra, périphériques, informations système ou autres ressources.
- [ ] Préciser si l’opération est synchrone ou asynchrone, si elle peut être annulée et sur quel fil elle s’exécute.
- [ ] Énumérer les résultats d’erreur, les délais d’attente, les cas de permission refusée et les règles de libération des ressources.
- [ ] Marquer chaque dépendance selon son statut : réutilisable sous réserve, à remplacer ou à vérifier sur la cible.
Ne classez pas « lecture de fichier » ou « caméra » comme des capacités acquises simplement parce que l’application les propose déjà ailleurs. Pour les fichiers, vérifiez le sélecteur et les règles d’accès présentés dans les documents officiels sur Picker. Pour la caméra, examinez les interfaces et conditions décrites dans le guide de développement caméra en C/C++. Ces documents servent à déterminer les points à contrôler ; ils ne justifient pas, à eux seuls, l’affirmation que toutes les interfaces sont disponibles dans chaque configuration HarmonyOS PC.
Un cas pratique aide à rendre cet inventaire exploitable : l’application demande à la personne qui l’utilise de sélectionner un fichier, puis en lit le contenu pour appliquer une règle métier. Il faut distinguer la sélection de la ressource, son ouverture, son traitement et le retour du résultat. La règle métier peut rester commune si elle est indépendante de la plateforme ; la manière d’obtenir l’accès au fichier, elle, doit être validée séparément.
Étape de conception : transformer IPC en contrat indépendant
Avant d’écrire un pont natif, stabilisez le contrat utilisé par le code métier. Pour le scénario de lecture, ce contrat peut exprimer une intention telle que « demander la sélection d’un fichier et retourner un résultat exploitable ou une erreur caractérisée ». Il doit indiquer quels paramètres sont nécessaires, quel résultat est transmis, comment l’annulation est représentée et quelles erreurs sont distinguées.
La documentation d’Electron décrit IPC comme une communication entre processus, avec des mécanismes et des canaux propres à son modèle (guide officiel IPC d’Electron). Ce modèle est utile pour comprendre l’application actuelle, mais il ne définit pas l’architecture cible. Il faut éviter de remplacer chaque canal Electron par un composant ArkTS supposé équivalent : un canal peut mélanger la règle métier, la sérialisation, les autorisations et l’accès natif.
Une séparation plus sûre distingue trois responsabilités :
- Contrat métier : décrit la demande et le résultat sans nommer une API de système.
- Adaptateur de plateforme : traduit ce contrat vers l’implémentation existante d’Electron ou vers celle qui sera développée pour HarmonyOS.
- Capacité native : effectue uniquement l’opération système dont la disponibilité et les règles d’accès ont été vérifiées.
L’implémentation Electron peut ainsi continuer à servir les versions existantes pendant que l’adaptateur HarmonyOS est développé indépendamment. Si une interface officielle manque ou si l’accès n’est pas encore vérifié, le contrat reste en place et la fonction demeure explicitement indisponible ou reportée sur la cible, plutôt que d’être simulée par une hypothèse cachée.
Pour la demande de fichier, consignez en particulier le comportement lorsque la personne ferme le sélecteur, refuse l’accès ou choisit un fichier illisible. Un résultat « annulé » ne devrait pas être confondu avec une erreur d’accès, et une erreur native ne devrait pas être retournée comme une chaîne opaque que l’interface ne peut pas traiter.
Étape d’implémentation : n’exposer que les capacités vérifiées par Node-API
La documentation d’ArkTS Runtime et le guide Node-API décrivent des mécanismes d’interaction entre du code ArkTS ou JavaScript et des composants natifs C/C++. Le principe de migration est d’exposer une interface étroite à partir du code natif, puis de vérifier l’enregistrement, les conversions et l’appel depuis le contexte réel du projet. La documentation Node-API sur l’encapsulation d’objets donne un exemple de liaison à examiner, tandis que la présentation du runtime ArkTS aide à distinguer ce runtime de celui de Node.js.
Pour l’exemple de lecture d’un fichier, le découpage conceptuel pourrait être le suivant :
Contrat ArkTS :
demanderSelection() -> résultat ou erreur caractérisée
Adaptateur HarmonyOS :
appeler l’interface de sélection vérifiée
transmettre la ressource selon les règles documentées
retourner un résultat métier compréhensible
Module natif, uniquement si nécessaire et pris en charge :
enregistrer l’interface Node-API
convertir les arguments et les résultats
retourner les erreurs sans bloquer le fil principal
libérer les ressources selon leur cycle de vie
Ce pseudo-code décrit des responsabilités, pas une recette directement compilable. Il ne faut pas publier ni intégrer du code présenté comme exécutable tant que les noms d’API, la configuration du module, les outils de compilation et les permissions n’ont pas été confirmés dans le SDK et l’environnement visés. La documentation officielle doit guider l’implémentation ; un test de compilation et d’exécution sur la cible doit ensuite confirmer les détails de l’intégration.
Node-API n’est pas un convertisseur universel. Il ne rend pas automatiquement compatible une extension Node.js compilée pour Electron, ne remplace pas une bibliothèque système absente et ne transforme pas une DLL ou une bibliothèque partagée destinée à un autre système en module HarmonyOS utilisable. Il fournit un moyen de construire une liaison native lorsque les capacités nécessaires, les outils et les conditions de la plateforme sont effectivement disponibles.
Au moment de concevoir le pont, prévoyez explicitement :
- L’enregistrement du module : vérifier où et comment la cible attend que le composant soit exposé.
- Les conversions : définir la représentation des chaînes, chemins, nombres, objets et résultats, sans supposer qu’une structure Node.js peut être réutilisée telle quelle.
- La gestion des erreurs : distinguer annulation, refus d’autorisation, ressource inaccessible, erreur native et échec inattendu.
- L’asynchronisme : vérifier la séquence des rappels et empêcher qu’une opération potentiellement longue bloque l’interface.
- La durée de vie : libérer les objets natifs lorsque l’appel est terminé ou annulé, et tester les appels répétés.
- La construction : reproduire le chargement du module et sa compilation dans l’environnement officiellement pris en charge, plutôt que de se fier à une compilation locale non représentative.
Étape de validation : contrôler permissions, fichiers et caméra
La validation fonctionnelle doit vérifier le comportement réel, y compris les chemins qui ne réussissent pas. Pour les fichiers, commencez par le parcours de sélection documenté et contrôlez la portée de l’accès obtenu. Testez ensuite l’annulation, un fichier dont la lecture échoue et les erreurs remontées par l’adaptateur. N’utilisez pas une ancienne logique de chemins absolus comme preuve qu’un accès direct est autorisé.
Pour la caméra, traitez le cas séparément. Confirmez que l’interface choisie est documentée pour la cible, que la demande d’autorisation correspond au mécanisme requis et que l’application sait réagir à un refus, à l’absence de caméra ou à un échec d’initialisation. Un module Electron qui accédait à la caméra sur une autre plateforme n’est pas une preuve qu’un appel Node-API équivalent existe ou qu’il est autorisé sur HarmonyOS PC. Les attentes de l’application doivent être comparées aux guides officiels applicables, puis confrontées à un essai sur l’environnement disponible.
Dans les deux scénarios, enregistrez les événements utiles : début de l’opération, résultat, erreur, annulation et libération de la ressource. Contrôlez aussi si l’interface reste réactive, si l’ordre des rappels correspond au contrat et si un second appel fonctionne après un premier échec. Pour une application créative qui manipule des séquences audio ou vidéo, ces vérifications sont particulièrement importantes : un aperçu caméra, une capture ou une lecture de média peut impliquer des ressources et un rythme d’appel différents d’une simple lecture de document. Il faut mesurer et documenter le comportement obtenu, sans déduire des performances d’une autre plateforme.
Étape d’acceptation : comparer les options et fixer les critères d’arrêt
Le tableau ci-dessous sert à décider où investir le travail de migration. Il ne constitue pas une déclaration de compatibilité : chaque capacité doit être qualifiée à partir des documents et essais du projet.
| Option | Ce qui peut être conservé | Condition de décision | Risque principal |
|---|---|---|---|
| Partager la couche métier | Règles de validation, transformations et modèles indépendants du système | Les dépendances Node.js et système sont absentes ou isolées | Dépendance indirecte à une API propre à l’ancienne plateforme |
| Réécrire l’accès à une capacité documentée | Contrat métier et résultats attendus | API, permissions et méthode de construction confirmées pour la cible | Différences de comportement, d’erreur ou de cycle de vie |
| Maintenir un adaptateur en attente | Interface commune et implémentation Electron existante | Interface cible ou support SDK non vérifié | Fonction indisponible sur HarmonyOS jusqu’à validation |
| Reporter la fonction | Le reste de l’application qui ne dépend pas de cette capacité | Une capacité matérielle ou système essentielle n’est pas documentée ou testable | Décalage du périmètre produit, mais absence de compatibilité fictive |
La décision finale doit s’appuyer sur des preuves reproductibles plutôt que sur une liste de fonctions « probablement prises en charge ». Pour chaque fonctionnalité native, l’équipe doit pouvoir consigner les éléments suivants :
- [ ] Le projet se compile dans un environnement officiellement pris en charge et la procédure peut être répétée.
- [ ] L’application s’installe sur la cible ou dans l’environnement de débogage officiellement prévu.
- [ ] Le parcours normal fonctionne et le résultat correspond au contrat métier.
- [ ] Les permissions ont été accordées ou refusées selon le parcours prévu, sans accès implicite supposé.
- [ ] L’annulation, les erreurs et la reprise après échec ont été observées et consignées.
- [ ] Les appels répétés ne provoquent ni blocage de l’interface ni ressource native laissée ouverte.
- [ ] Chaque capacité non vérifiée reste signalée comme telle dans le périmètre et la date de livraison.
Si une interface critique, une permission ou un environnement de test n’est pas confirmé, conservez l’adaptateur et reportez cette capacité. Il est préférable de livrer une liste de fonctions explicitement exclues qu’une implémentation fondée sur des API supposées. La même règle s’applique à un éventuel outil de migration : tant qu’une annonce officielle et une vérification effective ne l’établissent pas, il ne faut ni en faire un prérequis du calendrier ni compter sur lui pour convertir les modules.
Questions fréquentes sur la migration native
Un module natif Node.js peut-il être repris sans modification ?
Non. Il peut dépendre de l’ABI d’Electron, d’API Node.js et d’appels système propres à son environnement d’origine. Node-API ne convertit pas automatiquement ce module. Il faut isoler sa fonction métier, confirmer la capacité équivalente sur HarmonyOS PC, puis construire et tester une liaison adaptée au SDK cible.
Comment appeler du C++ depuis ArkTS avec Node-API ?
Il faut suivre les guides officiels correspondant au runtime et au SDK sélectionnés : exposer une interface native, convertir les paramètres et résultats, puis traiter les erreurs et la durée de vie des ressources. L’enregistrement exact et les appels utilisables dépendent de l’environnement visé. Un schéma conceptuel ne doit donc pas être présenté comme du code fonctionnel avant compilation et essai sur la cible.
Que faut-il extraire des appels IPC d’Electron ?
Séparez la règle métier des détails de communication entre processus. Pour chaque opération, documentez l’appelant, les entrées, le résultat, l’annulation, les erreurs, les dépendances natives et le comportement asynchrone. Gardez un contrat stable et laissez chaque plateforme l’implémenter par son propre adaptateur, sans reproduire directement les frontières de processus d’Electron.
Comment traiter les autorisations pour les fichiers et la caméra ?
Vérifiez séparément chaque parcours au moyen des documents officiels applicables à la cible. Pour les fichiers, contrôlez le sélecteur, l’étendue de l’accès, l’annulation et les échecs de lecture. Pour la caméra, identifiez l’interface, l’autorisation et les erreurs de disponibilité. Les comportements de Windows, Linux ou d’Electron ne permettent pas de déduire ceux de HarmonyOS PC.
Choisir un environnement complémentaire sans le confondre avec la cible
Avant d’engager la migration, les équipes peuvent marquer dans l’inventaire chaque dépendance native et chaque capacité encore à confirmer, puis préparer un essai reproductible avec le SDK officiellement retenu. Si le projet doit aussi maintenir une version macOS ou produire des éléments créatifs audio et vidéo, un Mac distant loué auprès de KuzCloud peut compléter l’organisation pour ces tâches macOS ; il ne remplace pas la vérification du SDK HarmonyOS PC et ne doit pas être présenté comme un environnement de développement HarmonyOS sans preuve officielle. Les modalités d’accès peuvent être examinées dans la console KuzCloud et les questions de prise en main dans l’aide KuzCloud. Le parc local reste plus pertinent lorsqu’un accès physique constant à du matériel précis est indispensable ; l’environnement distant répond plutôt aux besoins temporaires de compilation et de test macOS, sans lever les incertitudes propres à la cible HarmonyOS.
Préparez votre migration dans un environnement Mac dédié
Avec KuzCloud, prenez en main un Mac à distance sur matériel dédié pour préparer vos outils et vérifier les composants Electron qui dépendent de macOS.
Disposez d’un accès root ainsi que de connexions SSH et VNC pour installer votre chaîne de travail et reproduire vos scénarios de validation.