DevOps / CI/CD

2026 HarmonyOS PC:Electronのローカルファイルアクセスはどう移行する?

2026 HarmonyOS PC:Electronのローカルファイルアクセスはどう移行する?

ファイルパスを置き換えたのに、利用者の書類を開けない。ElectronからHarmonyOS PCへの移行では、こうした権限境界の食い違いが起きます。

先に進めるのは、ElectronのパスやIPCを直接移植しないことです。沙箱内のデータ、利用者が許可する共有ディレクトリ、利用者が選ぶファイルに機能を分け、一般的な読み書きはArkTSのファイルAPIから検証します。C/C++資産の再利用が必要な場合に限り、対象環境で確認したうえでNode-APIを評価します。

対象は、ローカルファイルを扱う既存Electronアプリの技術責任者、クロスプラットフォーム設計者、C/C++エンジニアです。
カメラ移行やプラグイン全般の互換性監査ではなく、ファイルの読み書きと利用者の許可をどう設計し直すかに絞ります。

最終更新:2026年10月21日。公開情報は公共ディレクトリのアクセス要件とElectronのIPC仕様で照合しています。対象HarmonyOS PCの内測版、SDK、端末での動作確認を示す実測記録はないため、個別の対応可否や実行可能なコードは断定しません。

移行前に分けるべきなのは、ファイルの種類とアクセス主体です

Electronでは、メインプロセスでファイル操作を受け持ち、レンダラープロセスからIPCで要求する構成がよく使われます。IPCは開発者が定義する通信経路です。HarmonyOS PC向けには、同じ要求をそのまま渡すのではなく、「誰が、どのファイルに、何をするか」を業務操作として切り出します。ElectronのIPCガイドも、プロセス間の通信を定義済みのチャネルで行う設計を説明しています。

まず既存コードを、読み込み、保存、一覧取得、インポート・エクスポート、一時ファイルに分類します。それぞれについて、呼び出し元、保存期間、失敗時の戻り値を記録してください。パス文字列だけを一覧化すると、ユーザーが選んだファイルとアプリ専用データを同じ権限で扱う設計ミスを見落とします。

ファイルの扱い 移行時の基本方針 判断上の注意
アプリ専用の設定・作業データ アプリのファイル管理仕様に対応する保存先を確認する Electronのユーザーデータ用パスを固定値として移植しない
利用者が選ぶファイル 選択操作と、その後の読み書きを別の業務操作として定義する 選択の取り消しを失敗や空パスと混同しない
共有ディレクトリ 公開文書で対象端末と許可条件を確認してから利用する パス取得だけで読み書き可能とは扱わない
一時ファイル 作成場所、削除条件、アプリ終了後の扱いを決める 再起動後にも残る前提を置かない

アプリの沙箱と共有ディレクトリは同じアクセス範囲ではありません。Huaweiのアプリのファイルアクセス管理資料とディレクトリ許可の説明を照らし合わせ、保存先ごとに許可の要否を切り分けます。

第1段階:HarmonyOS PCの対象環境と許可条件を先に確認する

「HarmonyOS向けのAPIがある」ことと、「特定のHarmonyOS PC内測端末・SDKで使える」ことは別の確認事項です。公開文書では、共有ディレクトリへのアクセスに対応するシステム能力と利用者の許可が必要で、対象インターフェースには2in1端末に関する制限も記載されています。ディレクトリ許可の公式資料は、端末形態の条件も含めて確認してください。

この一般資料だけでは、特定のPC内測版やSDKでAPIが利用可能だとは証明できません。製品としての対応を決める前に、対象端末、SDK、アプリの権限設定、ユーザー操作の流れを組み合わせて確かめます。確認が終わるまでは、対応済みと告知せず、実装計画上の未確認項目として残します。

第2段階:ElectronのIPCを有限のファイル操作に置き換える

Electron IPCのチャンネル名や任意パスを、ArkTS側へそのまま公開する設計は避けます。たとえばレンダラーから「任意の場所を読み込む」命令を受けるのではなく、「選択した文書を読み込む」「編集結果を保存する」「出力ファイルを利用者に渡す」といった、製品機能に沿った操作に分けます。

契約には、入力・出力の型、許可状態、キャンセル、対象ファイルが見つからない場合、アクセス拒否時のエラーを含めます。結果を非同期で返し、画面側が許可要求や再選択を案内できるようにします。Electronのメインプロセスとレンダラーの境界を整理する際は、Electronのサンドボックスに関する説明も参照し、既存の分離設計を棚卸しに反映してください。

第3段階:共有ディレクトリの許可は、ファイル操作の前提として扱う

HarmonyOS PCの共有領域へアクセスする場合、パスを得られたことだけで権限が確定したと判断しないでください。許可の要求、利用者の選択、許可が得られた後の操作を別の状態として扱います。必要な権限と対象範囲は、共有ディレクトリに関する権限一覧を確認し、対象端末で実際に許可フローが使えるかを検証します。

たとえば、文書を読み込む画面で利用者が選択を取り消した場合は、アプリが勝手に別のパスを探すのではなく、操作を中断して再選択できる状態に戻します。許可がない、対象機能が利用できない、ファイルが消えている、といった結果は別々に記録すると、製品側の案内と障害調査の両方が明確になります。

第4段階:ArkTS File KitとNode-APIを要件で選ぶ

普通のファイル選択、読み込み、保存であれば、最初にArkTS File Kitの該当インターフェースが要件を満たすか確認します。移植を急ぐためだけにNode-APIを足すと、ネイティブ層のビルドや保守対象が増え、権限問題を解決しないまま複雑さだけが残る可能性があります。

選択肢 適する状況 主な確認点
ArkTSのファイルAPI 標準的な読み書きや選択操作で要件を満たせる 対象PC・SDKでのAPI対応と許可フロー
Node-APIによる橋渡し 既存のC/C++ファイル処理ロジックを再利用する価値がある ビルド成果物、対象SDKでのロード、権限の受け渡し
既存のElectron実装を維持 対象環境で必要なAPIや動作を確認できていない 対応を保留し、検証端末と受け入れ条件を決める

Node-APIはアプリのファイル権限を回避する仕組みではありません。再利用候補がある場合も、まずArkTS側で利用者の許可と操作対象を管理し、ネイティブ層には許可済みの処理に必要な値だけを渡す設計を検討します。HarmonyOSのNode-API利用ガイドとNode.jsのNode-API仕様を参照しつつ、名前が似ていることだけを根拠にElectron用ネイティブ拡張の互換性を見込まないでください。

第5段階:実ファイルを使い、許可から再起動まで確認する

検証は、APIが呼び出せるかだけで終わらせません。次の順で、対象端末とSDKを記録しながら確認します。

  • 沙箱内の保存先で、作成・読み込み・更新を行い、アプリの想定どおりに扱えるか確認します。
  • 利用者が許可するディレクトリを使い、許可前後の挙動と拒否時の画面を確認します。
  • ファイル選択を取り消し、エラー表示ではなく中断として処理できるか確認します。
  • 存在しないファイル、読み込み中の削除、同じ操作の繰り返しを試し、戻り値と画面状態を記録します。
  • 保存後にアプリを終了・再起動し、ファイルの残存と再アクセス時の許可状態を確認します。

各結果には、端末形態、SDK、許可の手順、対象ファイル、再現操作、返されたエラーを記録します。HarmonyOS PCの対象環境で確認できていない場合は、テスト結果を推定で補わず「未検証」と残すことが移行判断の条件です。

Electronのローカルファイルアクセス移行は、権限境界を先に変える

従来のElectron実装をパス置換だけで移すと、任意パスを渡すIPC、OSごとに異なる保存場所、利用者の許可を無視した処理が残ります。こうした構成は、対象端末でのアクセス拒否や、キャンセル時の誤処理につながります。共有領域を使う機能は、公開仕様と実機確認がそろうまで対応範囲を限定してください。

自社端末での継続検証が必要なら、HarmonyOS PCそのものとビルド・開発環境を分けて調達し、どの機材で何を確かめるかを先に決める方法があります。ProxyMacのリモートMacはMac上の開発・ビルド用途を補う選択肢ですが、HarmonyOS PCの実機でも、検証済みのHarmonyOSビルド環境でもありません。利用条件はProxyMacの案内で確認し、Mac上の作業が必要な期間だけ使う場合は日本向けプランを比較してください。ローカルファイル移行の受け入れ判定は、必ず対象HarmonyOS PCとSDKで行います。

移行後の開発・検証環境を、ProxyMacで整えませんか?

専用のMac mini M4をリモートで利用できるため、手元の端末に依存しない開発環境を用意できます。
SSHやVNC、ブラウザーから接続し、実装やビルド、動作確認を進められます。