2026 HarmonyOS PC: что проверить перед переносом нативных модулей Electron?
Перенос Electron-приложения на HarmonyOS PC следует начинать не с переписывания расширений, а с отделения бизнес-логики от платформенных вызовов: нативные модули и IPC нельзя считать совместимыми по умолчанию. Такой порядок подходит командам, которые готовы проверять каждую системную возможность по документации и целевой среде, а не переносить предположения о Windows, Linux или Node.js на новую платформу.
Архитекторам Electron он поможет оценить объём замены нативных зависимостей и выбрать первые модули для переноса.
Командам кроссплатформенной разработки — отделить общую логику от платформенных интерфейсов.
Техническим руководителям — зафиксировать проверяемые критерии готовности и основания для отсрочки.
Последняя проверка — 15 октября 2026 года. Сверены официальные материалы по разработке приложений для HarmonyOS PC, среде ArkTS и Node-API; доступность конкретных API необходимо повторно подтвердить для целевого SDK и оборудования.
Сначала определите границы переноса
Документация разработчика содержит вход в разработку приложений для HarmonyOS PC, но сам факт наличия официального направления разработки не подтверждает совместимость конкретного Node.js-расширения, интерфейса камеры или способа доступа к файлам. Поэтому решение нужно принимать на уровне отдельных возможностей, а не всего приложения как единого переносимого пакета.
Практично разделить код на три категории:
- Общий слой: бизнес-правила, валидация данных, форматирование, предметные модели и алгоритмы, которым не нужен прямой доступ к операционной системе.
- Платформенный адаптер: реализация выбора файла, работы с камерой, системными сведениями и другими возможностями, зависящими от целевой среды.
- Непроверенная область: вызовы, для которых пока не найдены применимые официальные API, подтверждённые права или успешный сценарий сборки и запуска на целевой среде.
Это разделение задаёт границу между тем, что можно сохранять, и тем, что ещё нельзя объявлять поддерживаемым. В частности, наличие похожего API в другой настольной системе не доказывает, что такой же способ доступа или набор разрешений доступен на HarmonyOS PC. Архитектурные предположения о ядре, песочнице и файловой модели также следует проверять по документации именно целевой версии.
Можно ли использовать Node.js-нативный плагин Electron без изменений? Нет оснований считать, что можно. В документации Electron описаны требования к нативным Node.js-модулям и их сборке для среды Electron; это не подтверждает совместимость модуля с другим рантаймом или системным интерфейсом. Проверяйте не только исходный код расширения, но и его ABI, зависимости, сборочные параметры и вызываемые функции. Руководство Electron по нативным Node.js-модулям полезно для аудита исходной реализации, но не является инструкцией по автоматической конвертации.
Переделайте аудит нативных зависимостей в карту возможностей
Инвентаризация только по именам файлов вроде camera-addon или file-helper обычно не показывает, что именно придётся менять. Составьте запись для каждого вызова из приложения в нативный слой. Зафиксируйте его вызывающий компонент, контракт аргументов и результата, системную зависимость, поток выполнения и поведение при ошибке. В отдельной графе укажите, какой факт должен быть подтверждён документацией или экспериментом в целевой среде.
| Вариант решения | Что оставить или сделать | Когда выбирать |
|---|---|---|
| Сохранить общую логику | Перенести бизнес-правила за платформенно-независимый интерфейс | Если алгоритм не зависит от Node.js, системных вызовов и интерфейсов ОС |
| Заменить платформенный вызов | Реализовать адаптер через подтверждённый API целевой среды | Если официальная документация описывает нужную возможность и её ограничения |
| Отложить возможность | Сохранить контракт, пометить реализацию как непроверенную | Если отсутствует подтверждение API, прав доступа или успешной сборки |
Для каждого элемента реестра удобно хранить:
- вызывающий экран или процесс, назначение операции и частоту её использования в реальных пользовательских сценариях;
- контракт данных, включая обязательные поля, допустимые значения, формат результата и ожидаемую ошибку;
- связь с исходным модулем, библиотеками, системными заголовками и внешними исполняемыми компонентами;
- условия потоков: синхронный ли вызов, может ли он выполнять ввод-вывод, где вызывается обратная функция и кто освобождает ресурсы;
- фактическое доказательство совместимости: ссылка на применимый API, запись теста или явная пометка «не проверено».
Такой реестр не превращает гипотезу в обещание. Например, у функции чтения файла нужно различать путь, выбранный пользователем, и произвольный путь, самостоятельно сформированный приложением. Нельзя делать вывод, что доступ к одному означает разрешение на другое. Аналогично вызов камеры в существующем Electron-плагине подтверждает лишь поведение текущей реализации, но не интерфейс для новой платформы.
Отделите IPC от бизнес-контракта
IPC в Electron связывает процессы приложения, однако границы этих процессов не следует механически переносить на компоненты HarmonyOS PC. Начните с назначения сообщения: какие данные передаются, какая операция выполняется, как сообщается отмена и что происходит при ошибке. Описание IPC в документации Electron поможет проследить существующие каналы и вызовы, но не определяет архитектуру нового приложения.
Какие интерфейсы разобрать до замены Electron IPC? Как минимум те, через которые вызывается файловый доступ, камера, системная информация или другой нативный функционал. Для каждого контракта определите вход, результат, ошибочные состояния, асинхронность и владельца ресурса. Отдельно пометьте IPC-сообщения, которые смешивают бизнес-правила и прямой вызов платформенного API: их нужно разделить до реализации адаптера.
Для примера с чтением выбранного пользователем файла контракт можно описать так:
Выбрать документ:
вход: допустимые типы данных и назначение операции
результат: дескриптор или ссылка, разрешённая целевой системой
исходы: успешно, пользователь отменил, нет доступа, ошибка чтения
выполнение: асинхронное; завершение передаётся через результат или ошибку
Это описание намеренно не обещает, что конкретный путь, файловый дескриптор или модель разрешений уже подтверждены для HarmonyOS PC. Оно фиксирует наблюдаемое поведение приложения, которое должны реализовать платформенные адаптеры. В действующем Electron-варианте адаптер продолжает вызывать текущий IPC. Новая реализация получает отдельный вход для ArkTS и целевых API. Общие правила обработки результата остаются выше обоих адаптеров.
Такое разделение позволяет проверять новую реализацию без переписывания доменной логики и поддерживать прежнюю платформу, пока перенос не прошёл приёмку. Оно также предотвращает типичную ошибку, когда имя канала IPC напрямую становится названием функции нового модуля, хотя семантика, границы доверия и жизненный цикл ресурсов могут отличаться.
Подключайте ArkTS Node-API только к подтверждённому коду
Как устроен вызов C++ из ArkTS через Node-API? Практическая схема состоит в том, чтобы определить интерфейс модуля, зарегистрировать его в целевой среде, преобразовать значения между ArkTS/JavaScript и C/C++, выполнить разрешённую операцию и вернуть результат либо ошибку с контролируемым жизненным циклом ресурсов. Официальный обзор среды выполнения ArkTS и пример привязки объекта через Node-API служат исходными материалами для проверки конкретных механизмов.
При проектировании модуля разделите ответственность:
- Регистрация. Проверьте ожидаемую форму регистрации и экспорта в соответствии с целевой документацией и SDK. Не переносите конфигурацию сборки Electron как будто это конфигурация нового модуля.
- Преобразование аргументов. Для каждого входного значения установите допустимый тип, формат, границы и реакцию на некорректные данные. Ошибка преобразования должна возвращаться вызывающей стороне, а не исчезать в native-коде.
- Вызов C/C++. Оставьте здесь только подтверждённую низкоуровневую операцию. Бизнес-решения, выбор пользовательского файла и обработку интерфейсных сценариев лучше держать вне native-слоя.
- Результат и ошибка. Согласуйте способ передачи успешного ответа, отмены, отказа в доступе и системного сбоя с контрактом адаптера.
- Жизненный цикл. Определите, кто создаёт и освобождает объект, буфер, дескриптор или иной ресурс, а также что происходит при повторном вызове и закрытии компонента.
Ниже — схема проектирования, а не готовый код для сборки. Имена функций и формы регистрации здесь условны; их необходимо заменить согласно документации конкретного SDK и проверить в целевом окружении.
ArkTS-адаптер:
принять запрос на выбор документа
вызвать подтверждённый системный механизм
обработать отмену и отказ в доступе
передать выбранный объект в native-модуль, если он действительно нужен
C/C++-модуль:
проверить аргументы
выполнить подтверждённую операцию над ресурсом
вернуть результат либо типизированную ошибку
освободить принадлежащие модулю ресурсы
Node-API — это интерфейс взаимодействия кода с native-модулем в соответствующей среде, а не инструмент, который сам превращает любое расширение Node.js в совместимый компонент HarmonyOS PC. Он не переносит автоматически зависимости от операционной системы, произвольные системные библиотеки, сборочные сценарии или модель разрешений. Для сравнения с исходной архитектурой используйте электроновскую документацию о нативных модулях, а набор доступных функций и механизмов привязки подтверждайте по официальным материалам ArkTS и Node-API.
Не публикуйте фрагмент как рабочий пример, пока не проверены используемые объявления, способ регистрации, линковка, сборка, установка и вызов на поддерживаемой целевой среде. Если любой из этих этапов пока не выполнен, маркируйте реализацию как проект интерфейса, а не готовый перенос.
Проверьте файл и камеру как разные сценарии доступа
Какая адаптация нужна для файлов и камеры? Это разные возможности с разными API, правами, жизненным циклом и обработкой отказа. Не следует считать, что разрешение на выбор пользовательского файла даёт доступ ко всей файловой системе или что прежний плагин камеры автоматически соответствует API нового окружения.
Для файлового сценария сначала изучите официальное описание системного Picker. Проверьте, как приложение запускает выбор, что именно возвращается после подтверждения, как обрабатываются отмена и отказ, и в каком объёме разрешено дальнейшее чтение или изменение данных. Если приложение сохраняет результат для последующего использования, отдельно выясните правила срока действия доступа и повторного открытия. Указания из документации нужно сопоставить с целевой версией SDK — не подменять их поведением привычной настольной файловой системы.
Для камеры определите не только способ открыть устройство, но и порядок запроса доступа, допустимые состояния отказа, остановку потока и освобождение ресурсов при уходе с экрана или завершении операции. В качестве исходной точки используйте руководство по C/C++-интерфейсу камеры, затем проверьте применимость интерфейса именно к целевой среде HarmonyOS PC. Документация для другого сценария или устройства не подтверждает автоматически поддержку нужного приложения на ПК.
В обоих случаях зафиксируйте асинхронность и порядок событий. Камера может быть уже занята, пользователь может отказать в доступе, а выбор файла может быть отменён. Каждое такое состояние должно отображаться в контракте, а не маскироваться общим сообщением «ошибка». Следите и за тем, чтобы длительные native-операции не блокировали поток интерфейса: способ выполнения и передачи результата должен соответствовать документированным ограничениям целевой среды.
Проведите воспроизводимую проверку перед решением о выпуске
HarmonyOS PC-разработка требует проверки на целевой системе или в официально поддерживаемой среде отладки. Наличие проекта, который компилируется на машине разработчика, само по себе не подтверждает, что его можно установить, выдать необходимые разрешения и повторно выполнить ключевую операцию. Не публикуйте сведения об окружении, пока они не подтверждены реальной записью сборки и запуска.
Рабочая последовательность проверки:
- Зафиксируйте исходное состояние. Запишите целевую версию SDK, применяемую среду разработки, зависимости и точные команды сборки. Сверьте выбранные параметры с официальной страницей разработки HarmonyOS PC и не подменяйте целевой SDK другой конфигурацией.
- Соберите минимальный адаптер. Оставьте в нём один платформенный контракт и только необходимые зависимости. Убедитесь, что сборка нового слоя не опирается незаметно на бинарные артефакты Electron.
- Проверьте установку и запуск. Убедитесь, что артефакт можно установить в официально поддерживаемой среде, приложение стартует, а ошибки и журналы позволяют различить сбой загрузки модуля и отказ самой операции.
- Пройдите нормальный сценарий и отказ. Для файла проверьте выбор, отмену, чтение и отказ в доступе; для камеры — запрос доступа, отказ, запуск и штатное завершение. Сопоставляйте названия разрешений и API с документацией целевого SDK.
- Повторите операцию. Проверьте повторный вызов, возврат после ошибки и освобождение native-ресурсов. Фиксируйте зависания, неверный порядок обратных вызовов и состояния, которые остаются после закрытия компонента.
- Сохраните доказательства. Для каждого пункта отметьте среду, фактический результат и ссылку на подтверждающую документацию либо запись проверки. Значение «не проверено» не заменяйте формулировкой «поддерживается».
На этапе решения сопоставьте четыре критерия: подтверждённость интерфейса, ожидаемое поведение разрешений, устойчивость асинхронных вызовов и повторяемость сборки. Если хотя бы один ключевой критерий зависит от ещё не опубликованного API или неподтверждённого доступа к оборудованию, оставьте адаптерный контракт, но отложите реализацию этой возможности. Такой подход позволяет сохранить общий код и продолжить работу, не превращая неизвестное ограничение платформы в скрытую производственную зависимость.
Как решить, продолжать ли перенос конкретного модуля? Продолжайте, когда официальная документация описывает нужную возможность, целевой SDK позволяет построить модуль, а нормальный и ошибочный сценарии воспроизводимо проходят в поддерживаемой среде. Откладывайте, если не подтверждены API или разрешение, невозможно повторить сборку либо обработка отмены и освобождения ресурсов остаётся неопределённой. Это решение должно относиться к отдельной возможности, а не автоматически блокировать перенос всей бизнес-логики приложения.
Выберите среду по задачам, а не по привычке
Если команда сейчас разрабатывает приложение на Windows или Linux, эта среда может оставаться удобной для редактирования общего кода, но её привычные системные вызовы не доказывают совместимость с HarmonyOS PC. Перенос потребует отдельной проверки целевого SDK, прав и native-сборки; аналогично, среда macOS полезна для обслуживания и тестирования версии приложения под macOS, но не заменяет целевую проверку HarmonyOS PC.
Когда проекту параллельно нужна сборка и проверка macOS-версии, стоит сравнить содержание локального процесса с удалённой средой на Mac: локальная машина требует доступного оборудования и его сопровождения, а разрозненные сборочные узлы усложняют повторение конфигурации и передачу результата. Описание KuzCloud и консоль KuzCloud можно изучить, если для отдельного этапа требуется временный удалённый Mac. Такая аренда может упростить именно проверку macOS-сборки, но не подтверждает совместимость с HarmonyOS PC и не заменяет целевой SDK. При постоянной тяжёлой нагрузке или необходимости подключать физические устройства собственное оборудование может оказаться уместнее. Перед выбором сначала отметьте в карте миграции нативные зависимости и неподтверждённые возможности; затем определите, нужен ли проекту отдельный удалённый Mac для задач macOS.
Проверьте нативные зависимости Electron на удалённом Mac
В KuzCloud вы получаете выделенный Mac mini M4 для проверки сборки и поведения компонентов, зависящих от macOS.
Подключайтесь к физической машине по SSH или через VNC и работайте в привычной среде разработки.