在 Lynxtron 中使用 webview

<webview> 是 Lynx 中用于嵌入 Web 内容的元素。它的属性、事件和方法由 Lynx 元素 API 定义；本页只介绍在 Lynxtron 中如何通过官方维护的 npm 包引入这一能力。

考虑到 CEF 和 WebView 相关产物会显著增加包体积，Lynxtron 没有把 <webview> 默认内置到运行时中，而是以官方维护的 Lynx 原生能力库形式提供；其他官方 Lynx 元素仍按常规内置，可直接使用。

Lynxtron 官方维护的 @lynx-js/cef-webview 包提供了基于 Chromium Embedded Framework (CEF) 的原生视图能力。你可以像消费其他 Lynx 原生能力库一样安装这个包，在 Lynxtron 宿主进程中加载它的 Lynxtron 包入口，在主进程中初始化 CEF，然后使用 <webview> 这个 Lynx 元素。

原生侧的 <webview> 元素由包内 C++ library 通过 LYNX_REGISTER_ELEMENT(...) 注册。应用代码只需要确保 library 已加载并调用 initialize()，不需要调用更底层的 Lynx 注册 API。

工具链版本

本页的自动加载和打包流程已由 Lynxtron 0.0.22 正式工具链支持。请按 AutoLink 工具链版本说明配套使用 runtime、开发插件和 builder。

安装 npm 包

npm

yarn

pnpm

bun

deno

npm install @lynx-js/cef-webview

启用 AutoLink

AutoLink 自动发现并加载项目依赖中的原生库。Lynxtron 的构建插件 pluginLynxtron() 默认包含 AutoLink，create-lynxtron 已配置该插件，无需重复添加。

手动搭建项目可参考以下 Rspack 配置；使用 Rsbuild 时，将插件放入桌面端环境的 tools.rspack.plugins：

import { pluginLynxtron } from '@lynx-js/lynxtron-dev-plugins/rspack';

export default {
  target: 'electron-main',
  plugins: [
    pluginLynxtron({
      isDev: process.env.NODE_ENV === 'development',
      entry: './dist/desktop',
    }),
  ],
};

在主进程初始化 CEF

使用 webview 前需要初始化 CEF：在 app.whenReady() 后、创建 LynxWindow 或加载 Lynx bundle 之前调用 cefWebview.initialize()。

CEF 根据宿主应用标识选择存储目录；使用相同标识的多个实例可能发生存储冲突。initialize() 失败时会抛出异常，不要忽略错误后继续创建 WebView。参见初始化说明。

import { app, LynxWindow } from '@lynx-js/lynxtron';
import cefWebview from '@lynx-js/cef-webview/lynxtron';

app.whenReady().then(() => {
  cefWebview.initialize();

  const win = new LynxWindow({
    width: 1200,
    height: 800,
  });

  win.show();
  // 保留脚手架中开发态 loadURL / 生产态 loadFile 的加载逻辑。
});

将初始化合并到 src/main/desktop/main.ts，保留脚手架的 bundle 路径及按环境加载的代码，不要替换为硬编码路径。

使用 Lynx 元素

原生库加载且主进程完成 CEF 初始化后，就可以使用 <webview> 这个 Lynx 元素。

export function App() {
  return (
    <view style={{ width: '100%', height: '100%' }}>
      <webview
        src="https://www.example.com"
        style={{ width: '100%', height: '100%' }}
      />
    </view>
  );
}

关于 <webview> 支持的属性、事件和方法，见 <webview> API。

打包注意事项

打包宿主构建时保持 pluginLynxtron() 启用，并让 electron-builder 的 directories.app 指向宿主构建的 output.path。执行项目的标准构建和打包命令后，lynxtron-builder 会将原生包保留在 ASAR 外，将 macOS CEF Framework 和 Helper apps 放入 Contents/Frameworks，并让 Windows 的 addon、DLL 和资源文件保持包内相对位置。应用无需添加 CEF 专用的复制脚本或逐库打包规则。

#在 Lynxtron 中使用 webview

#安装 npm 包

#启用 AutoLink

#在主进程初始化 CEF

#使用 Lynx 元素