2026 HarmonyOS PC : comment migrer l’accès aux fichiers locaux d’Electron ?

Pour migrer l’accès aux fichiers locaux d’Electron vers HarmonyOS PC, ne transposez ni les chemins ni les opérations IPC tels quels : redéfinissez d’abord les frontières entre données privées, fichiers choisis par l’utilisateur et répertoires partagés. Cette méthode convient aux équipes qui ont un produit Electron existant ; les interfaces disponibles devront toutefois être vérifiées sur l’appareil et le SDK HarmonyOS PC réellement visés avant toute promesse de compatibilité.
Cet article s’adresse aux responsables techniques qui chiffrent la refonte des accès locaux d’une application Electron.
Il concerne aussi les architectes multiplateformes qui veulent isoler ces accès derrière un contrat commun.
Les ingénieurs C et C++ y trouveront un critère pour décider si une passerelle native est justifiée.
Dernière vérification : 21 octobre 2026, à partir de la documentation développeur disponible sur les autorisations et les fichiers, ainsi que de la documentation officielle d’Electron. La disponibilité effective sur une version de HarmonyOS PC doit être confirmée sur l’environnement cible.
Migration de fichiers sur HarmonyOS PC : les chemins ne suffisent plus
Dans un projet Electron, une fonction de lecture ou d’écriture peut sembler n’être qu’un appel à fs. En pratique, son comportement dépend souvent de plusieurs couches : le processus qui l’appelle, les contrôles effectués dans le processus principal, la manière dont l’utilisateur désigne le fichier et la durée de conservation du résultat. Sur une autre plateforme, remplacer le chemin local par un chemin supposé équivalent ne reproduit pas ces garanties.
Le modèle de migration doit distinguer au minimum trois périmètres.
- Données privées de l’application. Il s’agit des fichiers dont l’application gère le cycle de vie, comme un index, un cache métier ou un brouillon interne. Leur emplacement et leur durée de conservation relèvent du modèle de fichiers de l’application ; ils ne sont pas interchangeables avec un dossier visible par l’utilisateur.
- Fichier choisi par l’utilisateur. L’utilisateur désigne un document à ouvrir ou un emplacement de destination. Le consentement fait partie de l’opération. La fonction métier doit recevoir un résultat de sélection ou un refus, pas supposer qu’un chemin connu reste accessible.
- Répertoire partagé. Un dossier commun, tel qu’un emplacement destiné aux documents de l’utilisateur, relève de règles d’accès spécifiques. La documentation sur la demande d’autorisation pour un répertoire décrit un parcours associé à une capacité système et à une autorisation de l’utilisateur. Elle précise également une restriction aux appareils 2-en-1. Ce point ne suffit pas à garantir la disponibilité de l’interface dans une version précise de HarmonyOS PC.
La séparation est déterminante : l’obtention d’un chemin vers un répertoire ne démontre pas, à elle seule, que l’application possède le droit d’y lire ou d’y écrire. Les conditions associées aux autorisations de répertoires partagés doivent être rapprochées de la capacité effectivement prise en charge par l’appareil cible.
Point de vigilance : les règles générales de HarmonyOS ne constituent pas une certification de compatibilité pour une version de HarmonyOS PC en cours d’évaluation. Tant que l’interface n’a pas été exercée sur le SDK et le matériel visés, décrivez-la comme un point à vérifier, et non comme une fonction acquise.
Avant le portage, cartographier les opérations et leurs propriétaires
L’inventaire utile ne se limite pas à rechercher les occurrences de fs dans le dépôt. Une même opération peut être déclenchée par l’interface, validée par le processus principal, puis exécutée par un module natif. Recenser ces rôles évite de déplacer une capacité sensible dans une couche qui ne connaît ni le contexte ni l’autorisation.
Pour chaque opération, consignez son but métier, son appelant, sa destination et son résultat attendu. Classez les usages selon ces familles :
- Lecture : ouverture d’un document, import d’un projet, rechargement d’un fichier de configuration choisi par l’utilisateur.
- Écriture : sauvegarde d’un document, création d’un export, mise à jour de données privées.
- Parcours : recherche de fichiers dans un dossier et filtrage des résultats. Un parcours arbitraire de répertoires est différent de la sélection explicite d’un fichier.
- Import et export : transfert d’un document entre l’application et un emplacement choisi, avec un retour visible si l’opération échoue.
- Fichiers temporaires : éléments intermédiaires créés pendant un rendu, une conversion ou une exportation, avec une règle définie de suppression ou de conservation.
Un tableau de recensement interne peut associer à chaque entrée : le nom de l’opération, le déclencheur, le type de contenu, le périmètre de stockage, le comportement en cas d’annulation et l’erreur remontée. Le but n’est pas d’accumuler des chemins, mais de rendre explicite le contrat implicite du produit.
Par exemple, une application de création audio peut ouvrir un fichier de session, lire des médias sélectionnés et exporter un rendu vers une destination choisie. Ces étapes ne devraient pas dépendre d’un accès général aux dossiers personnels. Une application de design peut, elle aussi, importer des images ou enregistrer un livrable sans exposer au moteur d’interface la capacité de parcourir librement tout le disque.
Côté Electron, les échanges entre processus passent par des canaux définis par l’application, plutôt que par un mécanisme magique de partage de toutes les opérations locales. La documentation IPC d’Electron détaille cette communication. Pour la migration, conservez l’idée d’un point de contrôle, mais remplacez les messages trop génériques comme « exécuter cette fonction système » par des opérations métier nommées et validables.
Le bac à sable apporte une autre limite utile à préserver. La documentation d’Electron sur le bac à sable des processus explique le modèle de séparation entre le processus d’interface et les capacités privilégiées. La nouvelle architecture doit garder cette séparation fonctionnelle, même si l’implémentation cible n’utilise pas les mêmes processus.
Contrat commun ou accès direct : choisir une frontière explicite
Le choix le plus robuste consiste à définir une interface métier qui ne divulgue pas un accès général au système de fichiers. L’interface peut demander « choisir un document », « lire le document sélectionné », « enregistrer le résultat » ou « exporter le rendu ». Elle n’a pas besoin de demander « ouvrir n’importe quel chemin transmis par le moteur d’affichage ».
Un contrat indépendant de la plateforme devrait préciser les éléments suivants :
- Entrée : l’opération, les paramètres nécessaires et, si pertinent, la référence à une sélection obtenue par le système.
- Sortie : le contenu ou le résultat de l’enregistrement, ainsi que les métadonnées indispensables au métier.
- État d’autorisation : accord, refus, annulation, autorisation absente ou capacité indisponible.
- Erreurs : fichier introuvable, format non accepté, échec d’écriture ou interruption.
- Comportement asynchrone : l’interface peut attendre le résultat sans bloquer le rendu ni confondre une opération lente avec un refus.
Dans Electron, ces opérations peuvent être acheminées par un canal IPC précis. Dans l’implémentation cible, la couche ArkTS peut relier le même contrat aux interfaces effectivement disponibles. Ainsi, le modèle métier reste stable sans prétendre qu’une interface HarmonyOS particulière est déjà confirmée sur tous les appareils.
La documentation de gestion des accès aux fichiers d’application est utile pour examiner les périmètres applicables. Elle ne remplace pas la vérification sur la cible : les conditions documentées, le type d’appareil, la version du SDK et le comportement de l’application doivent concorder.
Une erreur fréquente consiste à traiter le refus d’autorisation comme une exception technique à masquer. C’est une issue fonctionnelle. Si l’utilisateur annule le sélecteur, l’application doit pouvoir revenir à l’écran précédent sans créer un export vide. Si une capacité est indisponible, le produit doit proposer une autre action ou expliquer la limite, plutôt que répéter silencieusement l’accès.
Interface ArkTS ou Node-API : décider selon le besoin réel
Pour un accès ordinaire à un fichier choisi, à des données propres à l’application ou à un export, commencez par vérifier si les interfaces ArkTS documentées couvrent le besoin. ArkTS File Kit ne doit pas devenir une promesse générique : ses fonctions, ses prérequis et leur disponibilité doivent être recoupés avec la documentation et l’environnement visés.
Node-API est une possibilité d’interopérabilité, pas une autorisation d’ignorer le modèle de sécurité. La documentation HarmonyOS sur l’utilisation de Node-API doit être étudiée pour construire un pont natif compatible avec la cible. La référence de Node-API de Node.js décrit l’interface du côté Node.js, mais la ressemblance de nom ne prouve pas qu’une extension native Electron existante se chargera ou se comportera de la même manière sur HarmonyOS PC.
Voici le critère de décision à appliquer avant d’engager le portage natif :
| Option | À choisir lorsque… | Avantage | Limite à vérifier |
|---|---|---|---|
| Interface de fichiers ArkTS | Les opérations métier sont couvertes par les interfaces confirmées sur la cible. | La logique suit le modèle de plateforme et évite une couche native inutile. | Les autorisations, la forme d’appareil et le SDK doivent être validés. |
| Contrat métier avec sélection système | L’utilisateur doit choisir un fichier ou une destination, sans accès général aux dossiers. | L’intention et le consentement sont explicites ; le moteur d’interface ne reçoit pas un chemin arbitraire. | Le parcours exact de sélection doit être disponible sur l’environnement ciblé. |
| Pont Node-API vers du C ou du C++ | Une bibliothèque existante apporte une valeur réelle et ne peut pas être remplacée raisonnablement. | Le traitement partagé peut être conservé derrière une API limitée. | La compilation, le chargement, les types échangés et les règles d’accès doivent être testés séparément. |
La passerelle native est donc un choix conditionnel. Elle peut conserver un traitement de contenu en C ou C++, mais elle ne doit pas servir à contourner les contrôles de l’application. Si l’ancienne extension Electron combine lecture de fichiers, accès à des chemins arbitraires et traitement métier dans un même module, séparez ces responsabilités avant d’évaluer une réutilisation.
Une interface de pont bien limitée expose des opérations précises, par exemple transformer le contenu d’un fichier déjà sélectionné ou valider un flux de données. Elle ne devrait pas recevoir une chaîne de chemin venue directement de l’interface et l’ouvrir sans contrôle. Le contrat doit également prévoir les erreurs et les retours asynchrones, sans faire dépendre l’application d’une hypothèse sur la compatibilité binaire.
De l’inventaire à la recette sur l’appareil cible
La migration peut suivre un parcours vérifiable, sans fabriquer de code présenté comme exécutable sur une cible non testée.
- Fixez le périmètre de validation. Notez l’appareil, la version du SDK, le type d’application et les fonctions documentées que l’équipe veut utiliser. Si l’accès aux répertoires partagés est nécessaire, confrontez ces éléments aux conditions publiées et à la restriction d’appareil indiquée dans la documentation.
- Cartographiez les usages existants. Pour chaque appel
fset chaque canal IPC lié aux fichiers, identifiez le déclencheur, le processus appelant, le contenu concerné et le cycle de vie. Distinguez l’import, la sauvegarde, l’export, le parcours et les fichiers temporaires. - Classez chaque accès. Indiquez s’il relève des données privées, d’un fichier choisi ou d’un répertoire partagé. Toute opération qui ne peut pas être classée révèle un besoin métier encore trop vague.
- Écrivez le contrat avant le portage. Définissez l’entrée, le résultat, l’état d’autorisation et les erreurs attendues. Limitez les opérations proposées à celles que le produit utilise réellement ; écartez l’exposition d’une API générique de système de fichiers.
- Reliez le contrat aux interfaces confirmées. Vérifiez les capacités disponibles sur l’appareil et le SDK ciblés. Si une capacité n’est pas démontrée, marquez-la comme bloquante et gardez l’adaptateur en attente, au lieu de publier un exemple de code théorique comme s’il avait été exécuté.
- Décidez de la réutilisation native. Isolez les fonctions C ou C++ qui apportent un bénéfice concret. Testez séparément la construction et l’appel de la passerelle Node-API ; ne déduisez pas la compatibilité du fait qu’une extension fonctionne dans Electron.
- Exécutez la recette et conservez les preuves. Testez l’accès privé, un fichier sélectionné ou un emplacement autorisé, l’annulation, l’absence du fichier, les répétitions et l’état après redémarrage. Pour chaque résultat, consignez l’appareil, le SDK, la séquence d’autorisation et le retour observé.
Cette recette doit inclure les échecs, pas seulement l’ouverture réussie. Un utilisateur peut annuler une sélection. Le fichier peut avoir disparu entre sa sélection et sa lecture. Une écriture peut échouer après un changement de destination. Une seconde activation peut lancer une demande concurrente. Après redémarrage, le produit doit aussi vérifier si la référence ou l’autorisation utilisée précédemment est encore valable, plutôt que de la considérer permanente sans preuve.
La validation doit rester reproductible. Une note telle que « l’export fonctionne » ne suffit pas à distinguer une opération sur données privées d’un accès à un dossier partagé. Enregistrez l’action exacte, le statut d’autorisation, le résultat visible et le message d’erreur. Si un comportement n’a été observé que sur un appareil, ne le généralisez pas à toutes les formes d’appareil ou à toutes les versions.
À la date de vérification de cet article, les documents publics cités fournissent des règles générales sur les fichiers et les autorisations, mais ne permettent pas d’affirmer que chaque interface est ouverte dans chaque version ou appareil de HarmonyOS PC. Les annonces sur l’accès à un programme de test, la portée des API de bureau et l’existence d’un outil de migration doivent être vérifiées dans les communications officielles au moment où l’équipe planifie son intégration.
Questions fréquentes sur les fichiers Electron et HarmonyOS PC
Par où commencer pour déplacer les accès fs d’Electron vers HarmonyOS PC ?
Commencez par inventorier les opérations réellement utilisées, puis classez chaque fichier selon son emplacement et son cycle de vie : données privées de l’application, fichier choisi par l’utilisateur ou dossier partagé. Remplacez ensuite les appels génériques à fs par des opérations métier limitées. Cette séparation permet de tester les autorisations avant de choisir une interface ArkTS ou une éventuelle passerelle native.
Une application HarmonyOS PC peut-elle ouvrir directement le Bureau et les Documents ?
Ne partez pas du principe qu’un chemin connu donne un accès automatique. La documentation publique décrit des conditions de capacité et d’autorisation pour l’accès aux répertoires partagés, et indique une restriction de forme d’appareil. Cela ne confirme pas, à lui seul, la disponibilité dans une version donnée de HarmonyOS PC. Vérifiez l’appareil, le SDK et le parcours d’autorisation ciblés.
Où gérer les autorisations lors du remplacement des opérations IPC par ArkTS ?
La couche qui connaît l’opération demandée doit déclencher le parcours d’autorisation et renvoyer un résultat explicite au métier. Le processus principal ou son équivalent garde la décision d’accès ; l’interface ne reçoit pas un chemin arbitraire à ouvrir. Distinguez succès, refus, annulation et capacité indisponible afin que l’interface puisse proposer une action compréhensible.
Node-API est-il indispensable pour les fichiers locaux sur HarmonyOS PC ?
Non. Pour les opérations ordinaires, vérifiez d’abord si les interfaces de fichiers ArkTS documentées pour votre appareil et votre SDK couvrent le besoin. Une passerelle Node-API se justifie surtout pour conserver une bibliothèque C ou C++ utile. Elle ne confère pas de droits supplémentaires et la compatibilité d’une extension Node.js existante doit être vérifiée séparément.
Comment vérifier les refus d’accès et les fichiers manquants après la migration ?
Exécutez les mêmes scénarios sur l’appareil et le SDK réellement visés : accès privé, dossier autorisé, annulation du sélecteur, fichier absent, opérations répétées et redémarrage de l’application. Pour chaque résultat, conservez l’état d’autorisation, l’action demandée et l’erreur retournée. Ne qualifiez pas la migration de validée si seul le chemin heureux a été testé.
Pour les équipes qui travaillent à distance, un Mac loué peut servir à des tâches de développement ou de construction compatibles avec leur chaîne d’outils, mais il ne remplace pas un appareil HarmonyOS PC. Il ne prouve ni la disponibilité des API sur la cible, ni le fonctionnement d’un parcours d’autorisation, ni le chargement d’une extension native sur cette plateforme. Le recours à un Mac distant est donc à évaluer selon le travail à exécuter, sans le confondre avec un banc de validation HarmonyOS.
Si le besoin porte sur un environnement Mac temporaire pour le développement, les essais ou la préparation de livrables, ProxyMac peut être évalué en complément de l’appareil cible, et non comme substitut à celui-ci. Les modalités et limites de service sont à vérifier dans les informations d’aide ProxyMac et les conditions applicables.
FAQ
Pour aller plus loin
Préparez vos validations multiplateformes sur un Mac distant dédié
Avec ProxyMac, louez un Mac mini M4 physique dédié pour compiler et tester vos composants Electron dans un environnement macOS complet.
Accédez à votre Mac à distance par SSH ou VNC, et examinez vos flux de fichiers sans dépendre d’un poste local disponible.