2026 HarmonyOS NEXT: можно ли напрямую использовать сторонние библиотеки React Native?

В документации React Native описаны два способа организовать платформенный код: через отдельные платформенные файлы и через проверки платформы в коде (руководство по платформенному коду). Это помогает разделять реализацию, но не делает Android- или iOS-зависимость совместимой с HarmonyOS NEXT. Сохраняйте библиотеку только при наличии подходящей адаптации для React Native for OpenHarmony, совпадении версий и успешной проверке нужных сценариев на целевом устройстве. В остальных случаях выбирайте замену или планируйте отдельную работу по адаптации.
Эта проверка нужна архитекторам, которые решают, какие зависимости оставить в плане миграции.
Она также пригодится старшим разработчикам, проверяющим RNOH-адаптации, версии и нативные интерфейсы.
Тестировщикам и руководителям поставки она поможет фиксировать неподтверждённые зависимости как риски, а не как готовые решения.
Последняя проверка материала — 5 октября 2026 года. Сверены документация React Native, описание архитектуры и материалы по библиотекам React Native for OpenHarmony, а также опубликованные записи о выпусках проекта (архитектура RNOH, записи о выпусках, каталог библиотек RNOH). Состав адаптаций и их документация меняются, поэтому перед решением нужно сверить состояние конкретной зависимости повторно.
Совместимость сторонних библиотек React Native: граница между кодом и реализацией
Зависимость из приложения для Android или iOS нельзя считать готовой для HarmonyOS NEXT только потому, что её можно установить или что бизнес-код импортирует её без изменений. Важны не только интерфейс пакета и его JavaScript-часть, но и то, что библиотека делает под этим интерфейсом: обращается ли к платформенному API, создаёт ли нативное представление, запрашивает ли разрешения, реагирует ли на переходы приложения между состояниями.
В миграции полезно разделять понятия:
- Зависимость объявлена в проекте — пакет присутствует в манифесте и может быть разрешён менеджером пакетов.
- JavaScript-код запускается — модуль загружается и выполняет общую логику.
- Нативная реализация подключена — нужные платформенные части существуют и корректно вызываются через среду RNOH.
- Бизнес-сценарий работает — поведение, разрешения, интерфейс и жизненный цикл соответствуют требованиям приложения.
Эти уровни не взаимозаменяемы. Успешная сборка может подтвердить часть интеграции, но сама по себе не доказывает, что библиотека корректно обработает отказ в разрешении, возвращение приложения на экран или нестандартный результат системного вызова. Аналогично, пример из документации может демонстрировать базовый путь, но не всю конфигурацию и поведение, нужные продукту.
Платформенные файлы React Native помогают отделить реализацию для одной платформы от другой. Однако документация о таком разделении объясняет общий механизм React Native, а не поддержку конкретной библиотеки в HarmonyOS NEXT. Это различие особенно важно для пакетов, которые выглядят как обычный JavaScript-модуль, но внутри используют нативный мост или платформенный компонент.
Для каждого пакета на первичном проходе фиксируйте одну из четырёх категорий:
- найдена документация или отдельный пакет адаптации RNOH;
- реализация действительно платформонезависима, а вызываемые ею системные возможности доступны;
- есть эквивалентная зависимость, которую проще поддерживать в целевой среде;
- требуется собственная адаптация либо замена архитектурного решения.
Категория — это начальная гипотеза, а не доказательство совместимости. В частности, запись в каталоге адаптаций не следует трактовать как сертификацию или гарантию со стороны платформы. Описание конкретного проекта подтверждает только то, что авторы проекта заявили и документировали.
Как проверить, есть ли у библиотеки адаптация RNOH
Начинайте с официального названия исходного пакета и его фактически используемой версии в приложении. Затем ищите библиотеку в каталоге инструкций по сторонним библиотекам RNOH и проверяйте, что именно там опубликовано: совпадающее имя, отдельный пакет адаптации, руководство подключения или только упоминание библиотеки.
Не объединяйте эти свидетельства в одну формулировку «поддерживается». Например, краткая запись без инструкции может быть полезной зацепкой для проверки, но не показывает, какой функциональный охват проверялся. Руководство с шагами подключения говорит больше о способе интеграции, но его тоже нужно сопоставить с версиями и требованиями проекта. Если для пакета опубликована отдельная инструкция, читайте её вместе с документацией самой библиотеки. Так, описание подключения react-native-bootsplash для RNOH — конкретный материал для проверки интеграции, а не общее обещание о совместимости всех библиотек этого типа.
Полезно сохранять в миграционной записи прямую ссылку на найденный материал и короткую выдержку о его границах. Отмечайте, относится ли описание к той же библиотеке, тому же способу подключения и нужным функциям. Если документация говорит только о базовом запуске, не переносите это утверждение на функции, которые в ней не рассмотрены.
Отдельно оценивайте зависимости без платформенного кода. Чистая JavaScript-библиотека может не требовать нативной адаптации, но её готовность зависит от фактически используемых API. Если модуль обращается к возможностям, предоставляемым только Android или iOS, отсутствие нативного кода внутри самого пакета ещё не решает вопрос. Проследите вызовы от публичного интерфейса библиотеки до системных функций и проверьте, есть ли подходящий путь в целевом приложении.
Запись библиотеки в общественном каталоге — основание начать проверку, но не основание закрыть миграционный риск. Ищите подтверждение для конкретной версии, нужного функционала и целевого устройства.
Если найти адаптацию не удалось, не делайте вывод, что библиотека заведомо несовместима или что её обязательно нужно писать заново. Зафиксируйте статус как «адаптация не найдена», уточните у команды проекта, есть ли другая документация или пакет, и проверьте доступные альтернативы. Пока доказательств нет, зависимость должна оставаться в списке открытых рисков.
Совместимость версий и полнота сведений
Найденная адаптация не отвечает на следующий вопрос: подходит ли она конкретному приложению? Сопоставьте версии React Native, RNOH, адаптационного пакета и инструментов проекта. Не ограничивайтесь тем, что каждая версия указана где-либо отдельно: нужна проверка их совместного использования. Сверяйте это по документации пакета, его примечаниям к выпускам и записям проекта RNOH. Описание RNOH как платформенного расширения объясняет общий контекст расширения React Native, но не устанавливает совместимость конкретного набора зависимостей.
Используйте статусы, которые явно отражают качество свидетельств:
| Статус | Что подтверждено | Следующее действие |
|---|---|---|
| Подтверждено документацией | Указаны нужный пакет, способ интеграции и диапазон или набор совместимых версий | Сопоставить записи с фактическими версиями проекта |
| Требует сверки | Адаптация найдена, но условия версий не приведены или неполны | Проверить публикации проекта и запросить уточнение у сопровождающих |
| Версионный риск | Используемая версия проекта выходит за указанные условия или сведения относятся к другой сборке | Провести отдельную техническую проверку, не фиксировать совместимость заранее |
| Не найдено | Нет проверяемого описания адаптации для нужной библиотеки | Оценить замену, собственную адаптацию или отказ от зависимости |
Если в документации не заявлены версии, не выводите совместимость из сходства названий или наличия свежей публикации. Если пакет адаптации устарел, но в материалах нет однозначного статуса поддержки, это не доказывает, что он сломан; однако сопровождение становится отдельным риском, который потребуется принять и закрыть проверкой или заменой.
Версионный учёт должен опираться на конкретный проект. Запишите используемые в нём версии, а затем сопоставьте их с требованиями каждой адаптации и инструментов сборки. Для неопределённого интервала указывайте «не подтверждено», а не выбирайте ближайшее подходящее значение. Если зависимость приходится обновить, отдельно оцените изменение её публичного API и побочных эффектов: обновление ради адаптации может затронуть исходные платформы.
Возможности платформы и реальные сценарии
Наличие подходящей версии отвечает на вопрос о потенциальном подключении, но не о функциональном равенстве. Проверьте, какие системные возможности библиотека использует и что именно приложение должно получить от неё. Для доступа к камере, уведомлениям, биометрическим функциям, файловой системе или другим платформенным возможностям важны не только успешный вызов, но и разрешения, обработка отказа, возврат из системного интерфейса и корректное поведение при повторном запуске сценария. Проверяйте только те возможности, которые действительно используются вашим приложением, и сверяйте требования с документацией целевой платформы и адаптации.
Нативные модули ArkTS особенно важны там, где библиотеке недостаточно JavaScript-логики. Они связывают реализацию с возможностями среды целевого приложения. Поэтому при аудите выясняйте, существует ли нужный модуль, какие методы он предоставляет, как возвращает ошибки и согласуется ли его жизненный цикл с вызывающим кодом. Документация React Native о нативных модулях объясняет общие принципы модулей React Native; её нельзя использовать как подтверждение наличия готового модуля для RNOH.
Практический сценарий для проверки — приложение использует библиотеку запуска экрана и аналитику, а команда обнаруживает для первой отдельные инструкции подключения, но для второй находит только исходное описание для Android и iOS. Первый пакет получает статус «есть документированная адаптация, сценарий требует проверки». Второй не объявляется автоматически несовместимым: команда выясняет, какие события и платформенные вызовы задействованы, и ищет альтернативу или план адаптации. Так решение строится вокруг фактической роли зависимости, а не только её названия в манифесте.
Оцените минимум три уровня поведения:
- Основной путь: библиотека выполняет действие, ради которого её подключили.
- Ошибки и разрешения: обработаны отказ, недоступность возможности и некорректный ответ системы.
- Состояние приложения и интерфейс: результат корректен после возвращения в приложение; нативные элементы отображаются и управляются ожидаемым образом.
Если хотя бы один обязательный сценарий не покрыт, не записывайте полное повторное использование. Можно оставить пакет для ограниченного применения, но это решение требует явного описания границ: какие вызовы разрешены, что заменено и какие функции продукта остаются вне поддержки.
Решение о сохранении, замене или собственной адаптации
Сравнивайте не только стоимость первоначального подключения. У общественной адаптации может быть подходящая функциональность, но слабое сопровождение; у альтернативного пакета — яснее документация и понятнее ответственность, но потребуется поменять вызовы приложения. Самостоятельная адаптация даёт контроль над нужными функциями, однако добавляет обязанности по тестированию и сопровождению при обновлениях исходной библиотеки, React Native и RNOH.
| Вариант | Когда разумен | Что команда принимает на себя |
|---|---|---|
| Сохранить | Адаптация найдена, версии соответствуют опубликованным условиям, обязательные сценарии проверены на целевом устройстве | Контроль за изменениями пакета и повторная проверка при изменениях зависимостей |
| Заменить | Есть поддерживаемая альтернатива с нужным поведением и более понятной интеграцией | Миграцию API, проверку существующих платформ и оценку отличий в поведении |
| Адаптировать самостоятельно | Библиотека критична, а равноценная замена не закрывает требования продукта | Реализацию платформенного слоя, тесты, документацию и дальнейшее сопровождение |
| Отложить решение | Не хватает документации, сведений о версиях или результатов проверки сценариев | Сохранение зависимости в явном списке рисков и ответственного за следующий шаг |
Принцип выбора прост: сохраняйте пакет, если для него есть подходящая адаптация, совпадают условия версий и проходит целевая проверка сценариев. Заменяйте, если эквивалентная библиотека лучше документирована или её поведение проще проверить и поддерживать. Самостоятельную работу рассматривайте, когда функция критична, замена не подходит, а команда готова владеть платформенным кодом и его проверкой.
Наличие публичного репозитория не равно гарантии своевременного ответа на запросы. Посмотрите, есть ли недавние изменения, понятные инструкции обновления и реакция на открытые дефекты. Эти сведения — индикаторы, а не обещание будущего сопровождения. Если критичная функциональность зависит от неподдерживаемого кода, назначьте ответственного и определите, какой факт позволит снизить риск: подтверждение сопровождающего, собственная проверка или переход на замену.
Решение, которое можно перепроверить
Чтобы следующий участник миграции не восстанавливал аргументацию по переписке, создайте запись для каждой зависимости. Указывайте исходное имя библиотеки, её используемую версию, ссылку на адаптацию RNOH, сведения о совместимости, целевое устройство и результаты проверки. Добавляйте ограничения функциональности, выбранное решение и ответственного. Не объединяйте разные библиотеки в одну строку только потому, что они относятся к одной функции приложения.
Перед тем как закрыть запись, пройдите по списку:
- [ ] Указаны исходный пакет и его фактически используемая версия.
- [ ] Проверено наличие отдельного пакета или инструкции адаптации RNOH; сохранена ссылка на источник.
- [ ] Сверены опубликованные условия совместимости React Native, RNOH, адаптационного пакета и инструментов проекта.
- [ ] Зафиксировано, использует ли зависимость платформенные API, нативные представления, разрешения или платформенные модули.
- [ ] На целевом устройстве проверены бизнес-сценарий и его обработка ошибок, а не только установка или сборка.
- [ ] Указаны функциональные ограничения, решение «сохранить», «заменить» или «адаптировать» и ответственный за сопровождение.
- [ ] Неподтверждённые данные оставлены в списке миграционных рисков до получения документации или результатов проверки.
Открытые записи должны содержать конкретное условие закрытия. Например: получить документацию с подходящими условиями версии, проверить сценарий на целевом устройстве или завершить оценку альтернативы. Такая формулировка не позволяет принять отсутствие сведений за положительный результат.
При изменении версии React Native, RNOH или самой адаптации запись нужно пересмотреть, если это затрагивает задокументированные условия. То же относится к изменению используемого API библиотеки или требований продукта. Повторная проверка не обязана означать полный пересмотр всего проекта: она должна быть привязана к зависимости и к той границе, которая изменилась.
Для параллельной работы над приложением и средами Apple отдельно оцените, нужен ли команде облачный Mac: это может упростить доступ к macOS для соответствующих задач, но не заменяет инструменты HarmonyOS, реализацию адаптаций RNOH и проверку на целевом устройстве. Локальная машина может быть предпочтительнее для постоянной нагрузки или подключения физического оборудования; облачный Mac — для временного доступа и параллельной работы, если эти ограничения приемлемы. Перед выбором можно изучить варианты облачного Mac в ProxyMac и уточнить порядок работы через справочный раздел ProxyMac. Сначала сформируйте таблицу зависимостей и выделите, какие задачи действительно требуют Mac-среды: тогда аренда будет решением конкретной потребности команды, а не попыткой заменить ей проверку совместимости.