如何在宿主应用中集成 Lynx Node-API addon 并在页面中调用 requireNodeAddon【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynxLynx 提供了一组实验性experimental的运行时集成点允许宿主应用把 Node-API addon 暴露给 Lynx 页面。开源的 Explorer 示例应用实现了一套完整的宿主侧集成模式示例模块LynxNodeAPIModule加上共享原生加载器 LynxNodeAPI.cc页面 JS 通过requireNodeAddon(addon)按名称请求 addon加载器在原生侧完成加载与初始化把 addon 的 exports 发布到 JS 全局对象__lynx_node_addon_exports__上。本文围绕这条链路展开准备运行时依赖、把 addon 二进制打进宿主应用、注册宿主模块、为页面开启开关最后在页面中调用requireNodeAddon并确认 exports 可用。Android 和 Harmony 是打包步骤文档最完整的两个平台作为主路径Apple 平台走静态链接作为可选分支简要说明。准备条件SDK 版本与平台运行时依赖集成功能要求Lynx 3.9.x SDK 基线见 Lynx Node-API Addons 的 Integration Prerequisites 一节。各平台的运行时依赖如下平台运行时依赖AndroidPrimJS 3.9.x 运行时 匹配的libnapi_adapter.soHarmonyPrimJS 3.9.x 运行时 匹配的libnapi_adapter.soiOSPrimJS 3.9.x 运行时 最新兼容版本的LynxWeakNodeAPIiOS 还有两项额外要求应用启动时必须先一次性把 PrimJS 安装到LynxWeakNodeAPI桥接层之后才能使用 Explorer 环境如果同时通过 CocoaPods 集成PrimJS和LynxWeakNodeAPI当前必须开启generate_multiple_pod_projects否则两个库中同名的 Node-API 头文件会互相冲突。Explorer 示例中这些前置依赖的落点供对照Android 的 PrimJS 依赖在platform/android/lynx_android/build.gradleHarmony 的在 oh-package.json5iOS 的在explorer/darwin/ios/lynx_explorer/PodfileiOS 运行时桥接安装在explorer/darwin/ios/lynx_explorer/LynxExplorer/AppDelegate.mm。Lynx 本身不规定唯一的 addon 加载器实现上面这些属于集成前提模块名、方法名、加载方式、导出符号等留给宿主自定义。把 addon 集成进宿主应用addon 的命名规则各平台一致addon是去掉lib前缀和文件扩展名后的库基名。例如libsample.so对应requireNodeAddon(sample)。Android打包为 lib .soAndroid 采用动态库加载addon 需要以libaddon.so形式进入应用的 native library 目录见 Android Node-API Addons发布集成通过 Androidaar发布 addonaar内包含jni/abi/libaddon.soGradle 会自动把 native 库打进应用本地集成把libaddon.so拷入jniLibs.srcDirs列出的目录。Explorer 示例默认的手动放置位置是explorer/android/lynx_explorer/src/main/jniLibs/abi/。abi取值如arm64-v8a、armeabi-v7a、x86_64。如果 addon 二进制只覆盖部分 ABI在explorer/android/gradle.properties中配置构建 ABI 列表例如abiListarm64-v8aHarmonyhar 包或本地目录投放Harmony 通过har包把 addon 的.so带进应用包本地开发也可以把 addon 共享库放到explorer/harmony/lynx_explorer/src/main/cpp/napi_addons/abi/Explorer 的 CMake 构建会将其拷贝到 native 库输出目录见 Harmony Node-API Addons。构建本地 Explorer 应用前需要先为 Harmony 的 workspace、app 和 native 类型包安装 OHPM 依赖ohpm install --all cd lynx_explorer ohpm install --all cd src/main/cpp/types/liblynx_napi_addon_loader ohpm install --allApple 平台可选分支静态链接Android/Harmony/Windows 使用动态 addon 二进制iOS/macOS 偏好静态集成——把 addon 链接进宿主应用并在构建中包含一次生成的addon_use.h头文件让NAPI_USE保留 addon 的静态注册入口。具体步骤见各平台文档iOSpodspec 与 xcframework 集成、macOS静态库集成。Windows 的 app-local 打包见 Windows。宿主侧注册模块并绑定运行时环境页面请求需要经宿主模块桥接到原生加载器。Explorer 示例中宿主侧要做两件事注册名为LynxNodeAPI的页面可见模块以及在运行时 attach 时把 runtime 专属的napi_env绑定下来。Android在模块适配层注册类注意注册的是类而不是实例SDK 会为每个页面注入LynxContext// explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/LynxModuleAdapter.java LynxEnv.inst().registerModule(LynxNodeAPI, LynxNodeAPIModule.class);LynxNodeAPIModule.java 在类加载时载入原生加载库lynx_napi_addon_loader优先走宿主/引擎提供的 loader否则回退到System.loadLibrary运行时 attach 回调把napi_env按runtimeId存入静态映射。HarmonyLynxNodeAPIModule.ets 是SendableLynxModule通过Sendable的 token 对象管理 envrequireNodeAddon最终调用原生库liblynx_napi_addon_loader.so暴露的requireNodeAddonByToken(token.id, addonName)。各平台注册与桥接的完整文件清单Android/iOS/Harmony/macOS/Windows在 Lynx Node-API Addons 的 Example Files 各小节中列出可对照阅读。共享加载器实现统一在 LynxNodeAPI.h 与 LynxNodeAPI.cc。为页面开启 Node-API 集成当前 Explorer 示例中只有页面 URL 的 query 带上enable_napi_addon1或enable_napi_addontrue时Node-API 示例集成才会生效。例如Androidfile://lynx?local://homepage.lynx.bundle?enable_napi_addon1Harmonyfile://lynx?local://main.lynx.bundle?enable_napi_addon1Android 模块中的失败日志也印证了这一点当拿不到napi_env时会打印requireNodeAddon failed: napiEnv missing/invalid ... Ensure enable_napi_addon is enabled and runtime attach callback has been received。在页面中调用 requireNodeAddon示例模块LynxNodeAPI只暴露一个宿主方法requireNodeAddon(addonName)。addonName必须与库基名匹配去掉lib前缀与扩展名Android libsample.so - requireNodeAddon(sample) Harmony libsample.so - requireNodeAddon(sample) iOS 静态注册为 sample - requireNodeAddon(sample) Windows sample.node / sample.dll - requireNodeAddon(sample)页面侧的调用形态来自 Explorer 的类型声明 typing.d.ts// typing.d.ts 中的声明 interface NativeModulesMap { LynxNodeAPI?: { requireNodeAddon(addonName: string): void; }; } declare var __lynx_node_addon_exports__: | Recordstring, Recordstring, (...args: unknown[]) unknown | undefined;注意requireNodeAddon返回void它只是触发原生侧加载与初始化结果不通过返回值传递而是由加载器发布到全局对象上。页面 JS 的完整调用与读取路径如下// 1. 触发宿主加载 addon前提页面 URL 带 enable_napi_addon1 NativeModules.LynxNodeAPI.requireNodeAddon(sample); // 2. 加载器完成后addon 的 exports 挂在全局对象上 // 键为调用 requireNodeAddon 时传入的名字 const sampleExports globalThis.__lynx_node_addon_exports__ globalThis.__lynx_node_addon_exports__[sample];结果验证与失败现象成功判定共享加载器初始化 addon 后会确保全局存在__lynx_node_addon_exports__对象若不存在则创建并把该 addon 的 exports 对象以传入的名字为键写入其中见 LynxNodeAPI.cc 的InitializeNodeModule。因此验证方式是调用后在页面 JS 中检查globalThis.__lynx_node_addon_exports__[sample]是否为对象、其上的导出函数是否可调。原生侧解析规则Android/Harmony/Windows 动态加载路径加载器按候选名依次尝试Android/Harmony 上为libaddon.so、libaddon.node等Windows 上为addon.node、addon.dll从进程默认库搜索路径解析名称有强约束只允许[A-Za-z0-9_.-]不允许/、\、..、、:和路径分隔符长度不超过 128。违反时直接输出Failed to load Node Addon: invalid name %s库文件全部候选都加载失败时输出Failed to load Node Addon %s. Last dlopen/dlsym error: %sWindows 为Last LoadLibrary/GetProcAddress error: %lu可据此判断是库不在搜索路径还是缺少依赖库加载成功但没有napi_register_module_v1导出符号时该候选会被卸载并继续尝试下一个同一 addon 只加载一次后续调用复用已加载的句柄并重新执行初始化。Apple 静态路径若napi_find_module_weak找不到注册表中的 addon会输出Failed to find statically linked Node Addon name. Ensure it is linked into the app so its constructor can call napi_module_register before calling requireNodeAddon.——即检查 addon 静态库是否已链接进应用、addon_use.h是否被包含。宿主模块层的日志Android原生加载库自身加载失败会打Failed to load native library: lynx_napi_addon_loaderruntimeId为 null 或napi_env缺失时分别有对应的requireNodeAddon failed: ...警告其中后两条都提示确认enable_napi_addon已开启且已收到 runtime attach 回调。限制与生产注意事项该能力与示例集成均为实验性库命名、打包规则和宿主集成细节仍可能变化。示例中的动态加载策略仅用于演示。文档明确要求生产集成不要依赖默认库搜索路径Windows 尤其如此应对addonName做白名单校验和/或限定固定基础目录、解析为该目录下的绝对规范路径、加载失败时返回可操作的诊断信息Windows 上优先使用带受限搜索行为的LoadLibraryExW而非默认 DLL 搜索顺序。本文只覆盖把已构建的 addon 集成进宿主应用。编写 addon 本身需要使用最新版lynx-js/weak-node-api其文档负责头文件、注册宏、导出符号和构建配置Explorer 文档不是编写 addon 的权威指南。【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何在宿主应用中集成 Lynx Node-API addon 并在页面中调用 requireNodeAddon
如何在宿主应用中集成 Lynx Node-API addon 并在页面中调用 requireNodeAddon【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynxLynx 提供了一组实验性experimental的运行时集成点允许宿主应用把 Node-API addon 暴露给 Lynx 页面。开源的 Explorer 示例应用实现了一套完整的宿主侧集成模式示例模块LynxNodeAPIModule加上共享原生加载器 LynxNodeAPI.cc页面 JS 通过requireNodeAddon(addon)按名称请求 addon加载器在原生侧完成加载与初始化把 addon 的 exports 发布到 JS 全局对象__lynx_node_addon_exports__上。本文围绕这条链路展开准备运行时依赖、把 addon 二进制打进宿主应用、注册宿主模块、为页面开启开关最后在页面中调用requireNodeAddon并确认 exports 可用。Android 和 Harmony 是打包步骤文档最完整的两个平台作为主路径Apple 平台走静态链接作为可选分支简要说明。准备条件SDK 版本与平台运行时依赖集成功能要求Lynx 3.9.x SDK 基线见 Lynx Node-API Addons 的 Integration Prerequisites 一节。各平台的运行时依赖如下平台运行时依赖AndroidPrimJS 3.9.x 运行时 匹配的libnapi_adapter.soHarmonyPrimJS 3.9.x 运行时 匹配的libnapi_adapter.soiOSPrimJS 3.9.x 运行时 最新兼容版本的LynxWeakNodeAPIiOS 还有两项额外要求应用启动时必须先一次性把 PrimJS 安装到LynxWeakNodeAPI桥接层之后才能使用 Explorer 环境如果同时通过 CocoaPods 集成PrimJS和LynxWeakNodeAPI当前必须开启generate_multiple_pod_projects否则两个库中同名的 Node-API 头文件会互相冲突。Explorer 示例中这些前置依赖的落点供对照Android 的 PrimJS 依赖在platform/android/lynx_android/build.gradleHarmony 的在 oh-package.json5iOS 的在explorer/darwin/ios/lynx_explorer/PodfileiOS 运行时桥接安装在explorer/darwin/ios/lynx_explorer/LynxExplorer/AppDelegate.mm。Lynx 本身不规定唯一的 addon 加载器实现上面这些属于集成前提模块名、方法名、加载方式、导出符号等留给宿主自定义。把 addon 集成进宿主应用addon 的命名规则各平台一致addon是去掉lib前缀和文件扩展名后的库基名。例如libsample.so对应requireNodeAddon(sample)。Android打包为 lib .soAndroid 采用动态库加载addon 需要以libaddon.so形式进入应用的 native library 目录见 Android Node-API Addons发布集成通过 Androidaar发布 addonaar内包含jni/abi/libaddon.soGradle 会自动把 native 库打进应用本地集成把libaddon.so拷入jniLibs.srcDirs列出的目录。Explorer 示例默认的手动放置位置是explorer/android/lynx_explorer/src/main/jniLibs/abi/。abi取值如arm64-v8a、armeabi-v7a、x86_64。如果 addon 二进制只覆盖部分 ABI在explorer/android/gradle.properties中配置构建 ABI 列表例如abiListarm64-v8aHarmonyhar 包或本地目录投放Harmony 通过har包把 addon 的.so带进应用包本地开发也可以把 addon 共享库放到explorer/harmony/lynx_explorer/src/main/cpp/napi_addons/abi/Explorer 的 CMake 构建会将其拷贝到 native 库输出目录见 Harmony Node-API Addons。构建本地 Explorer 应用前需要先为 Harmony 的 workspace、app 和 native 类型包安装 OHPM 依赖ohpm install --all cd lynx_explorer ohpm install --all cd src/main/cpp/types/liblynx_napi_addon_loader ohpm install --allApple 平台可选分支静态链接Android/Harmony/Windows 使用动态 addon 二进制iOS/macOS 偏好静态集成——把 addon 链接进宿主应用并在构建中包含一次生成的addon_use.h头文件让NAPI_USE保留 addon 的静态注册入口。具体步骤见各平台文档iOSpodspec 与 xcframework 集成、macOS静态库集成。Windows 的 app-local 打包见 Windows。宿主侧注册模块并绑定运行时环境页面请求需要经宿主模块桥接到原生加载器。Explorer 示例中宿主侧要做两件事注册名为LynxNodeAPI的页面可见模块以及在运行时 attach 时把 runtime 专属的napi_env绑定下来。Android在模块适配层注册类注意注册的是类而不是实例SDK 会为每个页面注入LynxContext// explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/LynxModuleAdapter.java LynxEnv.inst().registerModule(LynxNodeAPI, LynxNodeAPIModule.class);LynxNodeAPIModule.java 在类加载时载入原生加载库lynx_napi_addon_loader优先走宿主/引擎提供的 loader否则回退到System.loadLibrary运行时 attach 回调把napi_env按runtimeId存入静态映射。HarmonyLynxNodeAPIModule.ets 是SendableLynxModule通过Sendable的 token 对象管理 envrequireNodeAddon最终调用原生库liblynx_napi_addon_loader.so暴露的requireNodeAddonByToken(token.id, addonName)。各平台注册与桥接的完整文件清单Android/iOS/Harmony/macOS/Windows在 Lynx Node-API Addons 的 Example Files 各小节中列出可对照阅读。共享加载器实现统一在 LynxNodeAPI.h 与 LynxNodeAPI.cc。为页面开启 Node-API 集成当前 Explorer 示例中只有页面 URL 的 query 带上enable_napi_addon1或enable_napi_addontrue时Node-API 示例集成才会生效。例如Androidfile://lynx?local://homepage.lynx.bundle?enable_napi_addon1Harmonyfile://lynx?local://main.lynx.bundle?enable_napi_addon1Android 模块中的失败日志也印证了这一点当拿不到napi_env时会打印requireNodeAddon failed: napiEnv missing/invalid ... Ensure enable_napi_addon is enabled and runtime attach callback has been received。在页面中调用 requireNodeAddon示例模块LynxNodeAPI只暴露一个宿主方法requireNodeAddon(addonName)。addonName必须与库基名匹配去掉lib前缀与扩展名Android libsample.so - requireNodeAddon(sample) Harmony libsample.so - requireNodeAddon(sample) iOS 静态注册为 sample - requireNodeAddon(sample) Windows sample.node / sample.dll - requireNodeAddon(sample)页面侧的调用形态来自 Explorer 的类型声明 typing.d.ts// typing.d.ts 中的声明 interface NativeModulesMap { LynxNodeAPI?: { requireNodeAddon(addonName: string): void; }; } declare var __lynx_node_addon_exports__: | Recordstring, Recordstring, (...args: unknown[]) unknown | undefined;注意requireNodeAddon返回void它只是触发原生侧加载与初始化结果不通过返回值传递而是由加载器发布到全局对象上。页面 JS 的完整调用与读取路径如下// 1. 触发宿主加载 addon前提页面 URL 带 enable_napi_addon1 NativeModules.LynxNodeAPI.requireNodeAddon(sample); // 2. 加载器完成后addon 的 exports 挂在全局对象上 // 键为调用 requireNodeAddon 时传入的名字 const sampleExports globalThis.__lynx_node_addon_exports__ globalThis.__lynx_node_addon_exports__[sample];结果验证与失败现象成功判定共享加载器初始化 addon 后会确保全局存在__lynx_node_addon_exports__对象若不存在则创建并把该 addon 的 exports 对象以传入的名字为键写入其中见 LynxNodeAPI.cc 的InitializeNodeModule。因此验证方式是调用后在页面 JS 中检查globalThis.__lynx_node_addon_exports__[sample]是否为对象、其上的导出函数是否可调。原生侧解析规则Android/Harmony/Windows 动态加载路径加载器按候选名依次尝试Android/Harmony 上为libaddon.so、libaddon.node等Windows 上为addon.node、addon.dll从进程默认库搜索路径解析名称有强约束只允许[A-Za-z0-9_.-]不允许/、\、..、、:和路径分隔符长度不超过 128。违反时直接输出Failed to load Node Addon: invalid name %s库文件全部候选都加载失败时输出Failed to load Node Addon %s. Last dlopen/dlsym error: %sWindows 为Last LoadLibrary/GetProcAddress error: %lu可据此判断是库不在搜索路径还是缺少依赖库加载成功但没有napi_register_module_v1导出符号时该候选会被卸载并继续尝试下一个同一 addon 只加载一次后续调用复用已加载的句柄并重新执行初始化。Apple 静态路径若napi_find_module_weak找不到注册表中的 addon会输出Failed to find statically linked Node Addon name. Ensure it is linked into the app so its constructor can call napi_module_register before calling requireNodeAddon.——即检查 addon 静态库是否已链接进应用、addon_use.h是否被包含。宿主模块层的日志Android原生加载库自身加载失败会打Failed to load native library: lynx_napi_addon_loaderruntimeId为 null 或napi_env缺失时分别有对应的requireNodeAddon failed: ...警告其中后两条都提示确认enable_napi_addon已开启且已收到 runtime attach 回调。限制与生产注意事项该能力与示例集成均为实验性库命名、打包规则和宿主集成细节仍可能变化。示例中的动态加载策略仅用于演示。文档明确要求生产集成不要依赖默认库搜索路径Windows 尤其如此应对addonName做白名单校验和/或限定固定基础目录、解析为该目录下的绝对规范路径、加载失败时返回可操作的诊断信息Windows 上优先使用带受限搜索行为的LoadLibraryExW而非默认 DLL 搜索顺序。本文只覆盖把已构建的 addon 集成进宿主应用。编写 addon 本身需要使用最新版lynx-js/weak-node-api其文档负责头文件、注册宏、导出符号和构建配置Explorer 文档不是编写 addon 的权威指南。【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考