> For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt.

# 在 Lynxtron 中使用 webview

[`<webview>`](/next/zh/api/elements/built-in/webview.md) 是 Lynx
中用于嵌入 Web 内容的元素。它的属性、事件和方法由 Lynx 元素 API
定义；本页只介绍在 Lynxtron 中如何通过官方维护的 npm 包引入这一能力。

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

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

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

:::note 工具链版本

本页的自动加载和打包流程已由 Lynxtron `0.0.22` 正式工具链支持。请按 [AutoLink 工具链版本说明](/next/zh/guide/autolink.md#接入-autolink) 配套使用 runtime、开发插件和 builder。

:::

## 安装 npm 包


```sh [npm]
npm install @lynx-js/cef-webview
```

```sh [yarn]
yarn add @lynx-js/cef-webview
```

```sh [pnpm]
pnpm add @lynx-js/cef-webview
```

```sh [bun]
bun add @lynx-js/cef-webview
```

```sh [deno]
deno add npm:@lynx-js/cef-webview
```

## 启用 AutoLink

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

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

```ts
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。参见[初始化说明](/next/zh/lynxtron/api/@lynx-js/cef-webview/index.md#初始化结果与进程限制)。

```typescript {1-2,5}
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 元素。

```tsx
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](/next/zh/api/elements/built-in/webview.md)。

## 打包注意事项

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