DevOps / CI/CD

2026 HarmonyOS PC: как перенести доступ Electron к локальным файлам?

2026 HarmonyOS PC: как перенести доступ Electron к локальным файлам?

В приложении Electron чтение документа работает, а после переноса путь заканчивается отказом в доступе или неизвестным результатом операции.

Быстрый вариант: не переносите напрямую абсолютные пути и каналы IPC. Сначала разделите файлы приложения, выбранные пользователем документы и публичные каталоги; обычные операции проверяйте через интерфейсы ArkTS, а Node-API добавляйте только при подтверждённой необходимости повторно использовать код C/C++ и после проверки на целевом устройстве.

Эта инструкция для технических руководителей Electron-продуктов, которые оценивают объём адаптации файловых функций.
Она также пригодится архитекторам, отделяющим бизнес-операции от Electron IPC, и инженерам C/C++, проверяющим целесообразность мостового слоя.

Последнее обновление: 21 октября 2026 года. Сведения сверены с документацией HarmonyOS о доступе к публичным каталогам и описанием IPC в Electron. Общая документация не подтверждает наличие конкретного API в каждой версии HarmonyOS PC, SDK или на любом тестовом устройстве. До такой проверки выводы о поддержке остаются условными.

С чего начать перенос файловых операций из Electron в HarmonyOS PC?

Начните не с замены вызовов fs, а с инвентаризации пользовательских сценариев. Один и тот же путь в старом приложении может обозначать приватные данные приложения, документ, выбранный пользователем, или файл в публичном каталоге. В целевой системе это разные основания доступа, и одной строки с путём недостаточно, чтобы определить, разрешена ли операция.

У Electron доступ к файлам обычно организован через возможности основного процесса. Рендерер запрашивает действие через определённый канал, а обработчик решает, как выполнить его. В документации Electron IPC описан как обмен сообщениями между процессами по каналам, заданным приложением. Это не означает, что канал сам по себе выдаёт безопасное право на любой файл: это граница приложения, поведение которой задают разработчики. Документация об обмене IPC в Electron помогает разобрать исходную модель, но не определяет разрешения целевой платформы.

До реализации зафиксируйте исходные сценарии:

  • Чтение: какие типы файлов открываются, откуда приложение получает путь и должен ли документ оставаться доступным после закрытия окна.
  • Запись: создаётся ли новый файл, меняется существующий или результат сохраняется рядом с исходником.
  • Обход каталогов: нужны ли списки файлов, фильтрация по расширению, рекурсивный поиск или только доступ к конкретному выбранному документу.
  • Импорт и экспорт: инициирует ли действие пользователь или приложение выполняет его автоматически.
  • Временные данные: где создаются промежуточные файлы, когда они удаляются и что происходит при аварийном завершении.
  • Ошибки и повторные запросы: как различаются отмена выбора, отказ в разрешении, отсутствие файла, недоступный каталог и ошибка чтения.

Для каждого пункта полезно записать инициатора действия, операцию, ожидаемый срок жизни доступа, формат результата и поведение при сбое. Это выявляет скрытые зависимости: например, интерфейс может показывать «последние документы», хотя исходная реализация сохраняет лишь абсолютные пути, которые после перезапуска уже нельзя использовать.

Почему файловая модель важнее похожих системных путей

Путь к папке не равен разрешению. В материалах HarmonyOS получение доступа к публичным каталогам связано с предусмотренными системой возможностями и пользовательской авторизацией. Документация отдельно указывает ограничение для устройств формата «2-в-1». Это подтверждает границу, описанную в документации, но само по себе не доказывает, что нужный интерфейс доступен в конкретной сборке HarmonyOS PC или в используемом SDK. Сверяйте условия доступа к публичным каталогам с требованиями целевого устройства и SDK.

Разделите доступ на три категории:

  • Приватные данные приложения. Настройки, кэш и внутренние рабочие файлы должны обрабатываться через подтверждённые для приложения интерфейсы. Не рассчитывайте, что путь из старой установки или системная переменная окружения сохранит прежний смысл.
  • Файл, который выбирает пользователь. В этом сценарии пользователь обозначает конкретный документ. Приложению не обязательно получать общий доступ к каталогу, если бизнес-функция ограничена выбранным файлом.
  • Публичный каталог. Доступ к такой области требует проверки условий API, подходящего разрешения и поддержки на целевой форме устройства. Простое получение имени или пути каталога не следует трактовать как состоявшееся разрешение чтения и записи.

Такой подход объясняет важное отличие от механической миграции на другую настольную ОС. Даже если знакомый путь выглядит правдоподобно, это не гарантирует, что приложение имеет право выполнить операцию. В документации об управлении файловым доступом приложения рассматриваются правила платформы; конкретный рабочий сценарий всё равно нужно подтвердить на нужной конфигурации.

Планируя поддержку, заведите отдельные статусы для результата пользовательского выбора, отмены, отказа в разрешении, отсутствующей возможности и ошибки ввода-вывода. Не сводите их к одному сообщению «файл недоступен». Иначе продукт не сможет отличить штатную отмену диалога от несовместимости окружения или ошибки приложения.

Шаг 1. Зафиксируйте границы целевой среды

До изменения кода запишите, где будет запускаться приложение, какая версия SDK используется и какие файловые сценарии должны работать именно на этом устройстве. Отдельно проверьте доступность нужного API для выбранной формы устройства. Общие руководства по HarmonyOS нельзя автоматически переносить на конкретную версию HarmonyOS PC: они не являются доказательством поддержки каждого интерфейса в конкретной внутренней сборке или на каждом устройстве.

Составьте лист проверки, который можно приложить к задаче миграции:

  • целевое устройство и его форма;
  • версия SDK и используемая сборка приложения;
  • тип операции: чтение, запись, выбор, экспорт или обход каталога;
  • требуемое разрешение и способ его получения;
  • ожидаемое поведение при отказе и отмене;
  • подтверждённый способ хранения состояния доступа;
  • ссылка на документацию, по которой проверяли каждую возможность.

Если хотя бы одно из условий неизвестно, пометьте сценарий как «не подтверждён» и не обещайте его пользователям как поддерживаемый.

Шаг 2. Замените каналы IPC бизнес-контрактом

Вопрос о том, как заменить Electron IPC файловыми операциями ArkTS и где обрабатывать разрешение, решается не переносом каждого канала один к одному. Сначала определите небольшой набор намерений, которые нужны бизнес-логике: выбрать документ, прочитать содержимое, сохранить результат, экспортировать файл. Не выдавайте интерфейсу произвольный доступ к файловой системе и не передавайте ему универсальную функцию вида «прочитать любой путь».

Для каждого намерения зафиксируйте:

  • входные данные — например, фильтр типа документа или содержимое для сохранения;
  • ожидаемый результат — выбранный документ, завершённая запись или структурированная ошибка;
  • статус разрешения — доступ есть, требуется запрос, пользователь отказал или операция не поддерживается;
  • правила повторного вызова и последствия повторной записи;
  • границы доверия — какие данные может запросить интерфейс и что проверяет платформенный слой.

Удобно рассматривать контракт как набор операций, а не как имитацию прежнего API. Например, бизнес-слой просит «экспортировать отчёт», а адаптер платформы решает, каким подтверждённым способом предоставить пользователю выбор места сохранения. Это сохраняет смысл операции, даже если механизм доступа отличается от Electron.

Разрешение обрабатывайте на уровне адаптера, который знает о платформенном API, но не превращайте его в скрытую глобальную переменную. Бизнес-слой должен получить явный результат: операция выполнена, пользователь отменил действие, разрешение отклонено или функция недоступна. Такой контракт позволяет тестировать продуктовую реакцию без предположения, что системный запрос всегда завершится успехом.

Подходит ли ArkTS File Kit для обычных операций?

Для стандартных сценариев сначала проверьте возможности ArkTS File Kit в целевом SDK: чтение и запись нужного типа данных, выбор файла, получение доступа к каталогу и ожидаемая продолжительность этого доступа. Не переносите в этот этап предположение, что любой интерфейс из общей документации доступен именно в HarmonyOS PC. Подтверждайте каждый сценарий отдельно и отмечайте, какие условия предъявляются к устройству и разрешению.

Если подходящий интерфейс не подтверждён, оставьте операцию за платформенным адаптером с явно обозначенным состоянием «не реализовано для целевой среды». Это безопаснее, чем подменять проверку доступа прямым построением пути. Описание разрешений и операций с публичными каталогами сверяйте с официальными требованиями, но оно не заменяет запуск приложения на целевом устройстве.

Шаг 3. Решите, нужен ли мост C/C++

Сравните варианты по задаче, а не по сходству названий интерфейсов.

  • Операция покрывается подтверждённым интерфейсом ArkTS. Используйте платформенный адаптер. Преимущество — меньше связанного с C/C++ кода и меньше точек, где приходится согласовывать разрешения. Ограничение — нужно проверить реальные требования к типам данных, каталогам и жизненному циклу доступа.
  • Есть переносимая библиотека C/C++, но взаимодействие с файловой системой должно оставаться под контролем платформы. Оставьте выбор файла, проверку разрешения и управление платформенным объектом доступа в слое приложения. Передавайте библиотеке только данные или дескрипторы в том виде, который подтверждён целевой средой.
  • Существующая библиотека выполняет критичную обработку и не покрывается ArkTS. Тогда можно оценивать Node-API как мост для C/C++-кода, но отдельно проверять сборку, загрузку и совместимость для целевого SDK. Сам факт, что прежнее расширение использовало Node-API, не доказывает, что его можно загрузить в другом рантайме.

Документация Node-API для HarmonyOS описывает соответствующий механизм платформы. Документация Node.js о модуле Node-API относится к другой среде выполнения. Совпадающее название не подтверждает совместимость двоичного файла, ABI, инструментальной цепочки или способа загрузки. Для каждого компонента отдельно проверьте исходный код, зависимости, компилятор, целевую архитектуру и требования SDK.

Особенно важно не использовать Node-API как обход разрешений. Мост может предоставить способ вызвать нативный код, но это не даёт автоматического права читать произвольные каталоги. Авторизация должна быть частью продуктового сценария, а не предположением, спрятанным в C++-функции.

Инструмент выбора: отметьте подходящий путь миграции

Используйте этот список отдельно для каждого файлового сценария. Если обязательный пункт выбранного пути не подтверждён на целевом SDK и устройстве, не считайте сценарий готовым к выпуску.

  • [ ] Операция покрывается подтверждённым интерфейсом ArkTS. Выбирайте этот путь, если целевой SDK предоставляет нужную функцию на проверяемом устройстве. До выпуска подтвердите чтение или запись, обработку отказа и поведение после перезапуска.
  • [ ] Пользователю нужен один конкретный документ. Предпочитайте пользовательский выбор файла вместо общего доступа к каталогу, если операция не требует обходить папку. Проверьте, что результат выбора подходит для дальнейшей операции.
  • [ ] Сценарию нужен публичный каталог. Продолжайте только после проверки поддерживаемости для целевой формы устройства, условий разрешения и поведения при отмене или отказе. Если хотя бы одно условие неизвестно, пометьте доступ как неподтверждённый.
  • [ ] Нативная библиотека выполняет незаменимую обработку. Оставьте право выбора и доступа к файлам в платформенном слое, а библиотеке передавайте только проверенные данные или объекты доступа.
  • [ ] Выбрана интеграция через Node-API. Добавляйте мост лишь при наличии конкретной потребности в C/C++-коде и после проверки сборки, загрузки и совместимости на целевой среде. Если такой проверки нет, не делайте вывод о переносимости по одному лишь сходству названий API.

Этот список позволяет принять решение по каждому сценарию отдельно: не переписывать нативную логику без необходимости и не пытаться перенести старую модель доступа через новый рантайм без проверки разрешений.

Может ли приложение HarmonyOS PC напрямую читать рабочий стол и документы?

Не считайте доступ к рабочему столу и каталогу документов гарантированным. Для публичных каталогов документация указывает условия и ограничение по устройствам «2-в-1»; это не универсальное разрешение на доступ ко всем файлам пользователя. Выясните, поддерживает ли именно целевая сборка нужный сценарий, каким способом пользователь предоставляет доступ и сохраняется ли он после завершения приложения.

Проверьте продуктовый путь для каждого результата:

  • пользователь выбрал конкретный файл — приложение обрабатывает только этот выбор;
  • пользователь отказался от запроса — интерфейс возвращает его к предыдущему действию без ложного сообщения об аварии;
  • разрешение недоступно на устройстве — функция объясняет ограничение и предлагает поддерживаемый сценарий;
  • документ исчез или перемещён — операция сообщает об ошибке чтения, а не о проблеме разрешения;
  • запись запрещена — исходный файл не объявляется изменённым, пока результат не подтверждён.

Условия для публичных каталогов особенно важны для функций «открыть последнее» и автоматической загрузки. Если приложение хранит только абсолютный путь, повторное открытие после перезапуска может перестать работать. Поэтому сохраняйте не только путь, но и подтверждённый способ повторного получения доступа, если он предусмотрен целевой платформой. Такой механизм нельзя придумывать по аналогии: его нужно подтвердить документацией и тестом.

Шаг 4. Проведите сквозную проверку, а не только тест чтения

Перенос считается готовым не тогда, когда один документ открылся на машине разработчика. Проверяйте весь цикл: запрос действия, получение разрешения, выполнение операции, отображение результата и поведение после закрытия приложения.

План испытаний можно оформить так:

  • Песочница приложения: создать и прочитать файл в области, предназначенной для данных приложения; проверить, что интерфейс не принимает произвольный системный путь.
  • Выбранный пользователем документ: открыть файл, который пользователь указал через подтверждённый механизм; сверить фактическое содержимое и обработку неподдерживаемого формата.
  • Публичный каталог: запросить только требуемый доступ и проверить чтение либо запись в пределах выданных полномочий.
  • Отмена: закрыть системный выбор или отказать в разрешении; убедиться, что операция не помечена как успешная и интерфейс остаётся работоспособным.
  • Несуществующий объект: удалить или переместить тестовый файл до повторного открытия и проверить понятную ошибку.
  • Повтор операции: выполнить сохранение повторно и проверить, что приложение не создаёт неожиданные дубликаты и не перезаписывает данные без предусмотренного поведения.
  • Перезапуск: закрыть приложение и снова открыть рабочий документ; отдельно подтвердить, какие сведения о доступе остаются действительными.

Для каждого запуска сохраняйте устройство, SDK, состояние разрешений, исходные данные, действие пользователя и ожидаемый результат. Указывайте, был ли сценарий проверен на реальном целевом окружении или только разобран по документации. Пока фактического теста на HarmonyOS PC нет, не называйте пример кода рабочим и не публикуйте вывод о поддержке как установленный факт.

В этом переносе достаточно двух уровней контроля: контрактных тестов бизнес-операций и проверок на целевом устройстве. Первый уровень показывает, что приложение правильно различает успех, отмену и отказ. Второй подтверждает, что конкретный SDK и устройство действительно предоставляют нужное поведение. Успешный тест адаптера-заглушки не заменяет второй уровень.

Как встроить миграцию в план команды

Сначала отделите перенос файловых функций от аудита сторонних расширений. Здесь рассматриваются чтение, запись, выбор и доступ к каталогам; совместимость каждого Electron-плагина и перенос камер или других аппаратных устройств требуют отдельных проверок. Такое разделение предотвращает разрастание задачи и делает оценку точнее.

Затем назначьте владельцев трёх частей работы: бизнес-контракта, платформенного адаптера и подтверждения целевой среды. Если все решения остаются внутри одного большого обработчика, команде будет сложнее определить, где возникает отказ: в бизнес-логике, запросе разрешения или неподдерживаемом API.

Для каждого сценария держите краткую запись: исходная операция Electron, новый контракт, используемый интерфейс ArkTS, требование к разрешению, результат проверки и открытые вопросы. Если задача затрагивает C/C++, дополните запись результатом сборки и загрузки библиотеки на целевой среде. Не переносите выводы между SDK или устройствами без отдельного подтверждения.

В итоге решение сводится к трём развилкам. Если данные приватные — используйте подтверждённый механизм хранения приложения. Если нужен конкретный документ — проектируйте пользовательский выбор. Если необходим публичный каталог — проверяйте разрешение и ограничение устройства. Node-API рассматривайте только тогда, когда полезная нативная логика не заменяется штатным интерфейсом и её совместимость подтверждена отдельно.

Командам, которые параллельно готовят сборочную инфраструктуру или тестируют другие платформы, полезно отдельно оценить удалённую среду разработки. Но удалённый Mac не является целевым устройством HarmonyOS PC и сам по себе не подтверждает доступность SDK, разрешений или файлового API. Для временных задач сборки и проверки нагрузки аренда Mac может быть удобнее покупки отдельного оборудования; перед выбором можно изучить условия поддержки ProxyMac и актуальные варианты аренды. Если же команде нужен постоянный тяжёлый запуск или физическое подключение к конкретному тестовому устройству, собственная лаборатория может оказаться уместнее.

Проверьте приложение Electron на удалённом Mac

ProxyMac предоставляет выделенный Mac mini M4 с полноценной macOS для сборки и проверки сценариев приложения на стороне Mac.
Подключайтесь к удалённому рабочему столу через VNC или используйте SSH для работы в командной строке.