> 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 的知识基础。你将在本教程中学到的技术将会是构建任何 Lynxtron 桌面应用程序的基础。

**你将学到：**

- [使用 Lynxtron 实现自定义标题栏](#使用-lynxtron-实现自定义标题栏)
- [通过 Node.js 与 LynxView 通信实现窗口控制功能](#通过-nodejs-与-lynxview-通信实现窗口控制功能)
- [如何使用 Lynx 原生能力库中的 `<webview>` 元素](#lynx-webview-native-ui-extension)

## 我们要构建什么？

首先，让我们看看最终结果！我们将构建一个功能完整的多标签页浏览器，它包含：

- **自定义标题栏**：带有 "红绿灯" 窗口控制按钮（关闭、最小化、最大化）
- **标签页管理**：可以添加、切换和关闭多个标签页
- **导航栏**：包含前进、后退、刷新按钮和地址栏
- **网页渲染区域**：使用 [`<webview>`](/next/zh/api/elements/built-in/webview.md) 加载和显示网页内容

### 体验成品浏览器

成品 Browser demo 包含 Lynx UI、Node.js 主进程和 preload 桥接代码，均可在下方源码面板中查看。


**下面是一个示例: browser**

**Bundle:** `dist/desktop/main.lynx.bundle`

```ts
// Adapted from upstream browser-demo: isolate the Windows CEF profile.
import { app, LynxWindow, dialog } from '@lynx-js/lynxtron';
import { LYNX_BUNDLE_PATH } from './vendorPaths';
import path from 'path';
const cefWebview = require('@lynx-js/cef-webview/lynxtron');

app.whenReady().then(() => {
  if (process.platform === 'win32') app.setAppUserModelId('org.lynxtron.examples.browser');
  cefWebview.initialize();

  const w = new LynxWindow({
    width: 1400,
    height: 1100,
    lynxPreference: {
      preload: path.join(__dirname, 'preload.js'),
    },
    frame: false,
  });

  let isFullScreen = false;

  // Handle bridge calls from Lynx UI
  // @ts-ignore
  w.on(
    '-lynx-invoke',
    (callback: { sendReply(value: unknown): void }, name: string, data: any) => {
      // In our architecture, UI calls NativeModules.bridge.request({ method, params })
      console.log(
        `[PC_Host] NativeModule Call: bridge.${name}`,
        data,
        callback,
        name
      );

      if (name === 'showDialog') {
        const { message } = data;
        dialog.showMessageBox({ message });
        callback.sendReply(null);
      } else if (name === 'getAppVersion') {
        callback.sendReply(app.getVersion());
      } else if (name === 'hideWindow') {
        w.minimize();
        callback.sendReply(null);
      } else if (name === 'fullScreenWindow') {
        isFullScreen = !isFullScreen;
        console.log('Toggling full screen to:', isFullScreen);
        w.setFullScreen(isFullScreen);
        callback.sendReply(null);
      } else if (name === 'closeWindow') {
        callback.sendReply(null);
        w.close();
      } else if (name === 'maximizeWindow') {
        // Read native state on every click: OS actions can change it too.
        // unmaximize restores native bounds/state; setSize only resizes and
        // cannot correctly undo maximize or restore the original position.
        if (w.isMaximized()) w.unmaximize();
        else w.maximize();
        callback.sendReply(null);
      }
    }
  );

  // set minimum size
  const MIN_WIDTH = 400;
  const MIN_HEIGHT = 400;

  w.on('resize', () => {
    if (typeof w.getSize === 'function') {
      const [width, height] = w.getSize();
      if (typeof width === 'number' && typeof height === 'number') {
        const targetW = Math.max(width, MIN_WIDTH);
        const targetH = Math.max(height, MIN_HEIGHT);
        if (
          (targetW !== width || targetH !== height) &&
          typeof w.setSize === 'function'
        ) {
          w.setSize(targetW, targetH);
        }
      }
    }
  });

  w.show();
  w.loadFile(LYNX_BUNDLE_PATH);
});

```



## 教程设置

请查看我们详细的[安装文档](/next/zh/lynxtron/introduction.md)，该文档将指导你创建一个新的 Lynxtron 项目。

你可能会注意到该项目使用的是 TypeScript。虽然 Lynxtron 支持 TypeScript 和普通 JavaScript，但我们推荐使用 TypeScript，以提供更好的开发体验，包括静态类型检查和更好的编辑器智能感知。

### 安装 webview 原生库

`<webview>` 由可选包 `@lynx-js/cef-webview` 提供。在项目根目录安装：


```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
```

`create-lynxtron` 已配置桌面端的 `pluginLynxtron()`，无需重复添加。请先确认 [webview 入门中的工具链版本要求](/next/zh/lynxtron/Native-Libraries/Officially-Maintained-Libraries/cef-webview-getting-started.md)。配套工具链负责原生库加载与产物打包；应用仍需在创建窗口前初始化 CEF，见下一节。

如果使用 pnpm 11 且安装时提示相关构建脚本被阻止，在项目的 `pnpm-workspace.yaml` 中合并以下配置，再重新执行安装：

```yaml
allowBuilds:
  '@lynx-js/cef-webview': true
  '@lynx-js/lynxtron': true
  '@lynx-js/lynxtron-builder': true
```

## 使用 Lynxtron 实现自定义标题栏

由于浏览器的标题栏包含了标签页，而 Lynxtron 默认窗口的标题栏不符合要求，因此我们需要自定义标题栏。首先，我们需要创建一个无边框的窗口，以便完全自定义浏览器的外观（包括标题栏和 "红绿灯" 控制按钮）。

### 第一步：创建无边框窗口

在创建 `LynxWindow` 时，设置 `frame: false` 来移除系统默认的标题栏：

```typescript
// src/main/desktop/main.ts
import { app, LynxWindow } from '@lynx-js/lynxtron';
import cefWebview from '@lynx-js/cef-webview/lynxtron';
let mainWindow: LynxWindow | null = null;
function createWindow() {
  mainWindow = new LynxWindow({
    width: 1200,
    height: 800,
    frame: false, // 关键：移除系统边框
  });
  registerWindowControls(mainWindow);
}

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

将初始化调用合并到项目现有的启动流程中，并保留已有的 bundle 加载代码。CEF 必须在创建任何 `LynxWindow` 之前初始化。

CEF 根据宿主应用标识选择存储目录；使用相同标识的多个实例可能发生存储冲突。同一个浏览器支持多个标签页。若 `initialize()` 抛出异常，应停止启动并检查错误，不要继续创建 WebView。

![移除标题栏](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/browser_demo_frame_less.png)
### 第二步：自定义标题栏

移除系统标题栏后，我们需要实现浏览器的标题栏，主要由三部分组成：

1. **窗口控制按钮**：用于最大化、最小化和关闭浏览器
2. **标签页**：用于显示各个网页相应的标题信息
3. **添加按钮**：用于新增一个标签页

我们将这些组件都放在 top-bar 组件中，使用 Flexbox 布局排版，效果如下：

```tsx
// src/app/App.tsx
return (
  <view className="top-bar">
    <view className="traffic-lights">...</view>
    <scroll-view scroll-x className="tabs-container">
      {tabs.map((tab) => (
        <NewTab />
      ))}
      <view className="add-tab-btn" bindtap={handleAddTab}>
        +
      </view>
    </scroll-view>
  </view>
);
```

![自定义标题栏](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/browser_top_bar.png)
### 第三步：实现窗口拖拽

由于我们移除了系统的标题栏，用户无法通过默认方式拖动窗口。我们需要在自定义的顶部栏 (`.top-bar`) 上启用拖拽功能。

Lynxtron 支持使用 CSS 属性 [`-x-app-region: drag`](/next/zh/lynxtron/learn/Custom-Window-Styles.md#定义-ui-拖拽区域) 来指定可拖拽区域（类似于 Electron 的 `-webkit-app-region: drag`）。

```css
/* src/app/App.css */
.top-bar {
  /* 关键：启用窗口拖拽 */
  -x-app-region: drag;
}
```

\`
效果如下：


![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/browser_demo_top_bar_drag.gif)

## 通过 Node.js 与 LynxView 通信实现窗口控制功能

由于我们移除了系统原生的标题栏，我们需要自己实现 "关闭"、"最小化" 和 "最大化" 的功能。这需要通过 [Node.js 与 LynxView 通信](/next/zh/lynxtron/learn/Communication-Between-Node-And-Lynx.md)来实现。


#### Lynx JS 线程


```tsx
// src/app/App.tsx
const handleClose = () => {
  NativeModules.bridge.call('close', {}, () => {});
};

const handleMinimize = () => {
  NativeModules.bridge.call('minimize', {}, () => {});
};

const handleFullScreenTap = () => {
  NativeModules.bridge.call('maximize', {}, () => {});
};
```

#### Node JS 线程


```typescript
// src/main/desktop/main.ts
// 由上面的 createWindow() 调用。
function registerWindowControls(window: LynxWindow) {
  let isFullScreen = false;
  window.on('-lynx-invoke', (event, methodName, params) => {
    console.log('window is invoked', methodName, params);
    if (methodName === 'close') {
      console.log('Closing window...');
      event.sendReply(null);
      window.close();
    }

    if (methodName === 'minimize') {
      window.minimize();
      event.sendReply(null);
    }

    if (methodName === 'maximize') {
      isFullScreen = !isFullScreen;
      console.log('Toggling full screen to:', isFullScreen);
      window.setFullScreen(isFullScreen);
      event.sendReply(null);
    }
  });
}
```

这样浏览器窗口就可以进行"关闭"、"最小化"和"最大化"了：


![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/browser_demo_control.gif)

## 如何使用 [Lynx 原生能力库](/next/zh/lynxtron/Native-Libraries/Lynx-Native-Libraries.md)中的 `<webview>` 元素 \{#lynx-webview-native-ui-extension}

### 管理标签页

浏览器最核心的功能之一是多标签页管理。我们需要维护一个标签页列表的状态。

```tsx
// src/app/App.tsx
const [tabs, setTabs] = useState<Tab[]>([
  {
    id: '1',
    title: 'New Tab',
    url: 'https://www.lynxjs.org',
  },
]);
const [selectedTabId, setSelectedTabId] = useState<string>('1');

// 添加新标签页
const handleAddTab = () => {
  const newId = Date.now().toString();
  setTabs([...tabs, { id: newId, title: 'New Tab', url: '' }]);
  setSelectedTabId(newId);
};

// 关闭标签页
const handleRemoveTab = (id: string) => {
  const newTabs = tabs.filter((t) => t.id !== id);
  setTabs(newTabs);
  // 如果关闭的是当前选中的标签，需要切换到另一个标签
  if (id === selectedTabId && newTabs.length > 0) {
    setSelectedTabId(newTabs[newTabs.length - 1].id);
  }
};
```

至此，我们完成了标签页的新增和关闭功能：


![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/browser_demo_new_tab.gif)

### 添加 `<webview`> 组件

完成前面的原生库安装和 CEF 初始化后，可以在 Lynx UI 中直接使用 [`<webview>`](/next/zh/api/elements/built-in/webview.md) 加载外部网页，无需在 UI 代码中导入 CEF 包。

```tsx {5-9}
<view className="content-area">
  {tabs.map((tab) => (
    <view key={tab.id} className="tab-content">
      {tab.url && (
        <webview
          className="webview-container"
          id={`webview-${tab.id}`}
          src={tab.url}
        />
      )}
    </view>
  ))}
</view>
```

添加该元件后，我们就可以正常加载外部网页了：

![加载外部网页](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/browser_demo_webview.png)
### 标签页切换策略

为了在切换标签页时保持网页的状态（即不重新加载页面），我们**不同时销毁和创建** Webview。相反，我们渲染所有的 Webview，但通过 `z-index` 来控制哪个 Webview 显示在最上层。

```tsx
// src/app/App.tsx
<view className="content-area">
  {tabs.map((tab) => (
    <view
      key={tab.id}
      className="webview-wrapper"
      style={{ zIndex: selectedTabId === tab.id ? 1 : 0 }} // 只有选中的标签层级最高
    >
      <webview
        className="webview"
        src={tab.url}
        use-osr={true} // 开启离屏渲染
        enable-debug={true} // 开启调试功能
      />
    </view>
  ))}
</view>
```

这种 "堆叠" 策略确保了用户在标签间切换时体验流畅，页面状态得以保留，效果如下：


![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/browser_demo_switch_tab.gif)

### 导航与控制

我们需要通过 Lynx UI 上的按钮来控制 Webview 的行为（后退、刷新等）。这需要获取 `<webview>` 的引用并调用其方法。

```tsx
// src/app/App.tsx
const webviewRefs = useRef<Record<string, any>>({});
// 绑定 ref
<webview
  id={`webview-${tab.id}`}
  ref={(ref) => (webviewRefs.current[tab.id] = ref)}
/>;
// 刷新页面
const handleReload = () => {
  const ref = webviewRefs.current[selectedTabId];
  if (ref) {
    ref.invoke({ method: 'reload' }).exec();
  }
};
// 后退
const goBack = () => {
  const ref = webviewRefs.current[selectedTabId];
  if (ref) {
    // 通过 eval 执行页面内的 JS
    ref
      .invoke({
        method: 'eval',
        params: { func: 'window.history.back()' },
      })
      .exec();
  }
};
```

这样，浏览器就拥有了刷新和后退功能：


![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/browser_demo_go_back.gif)

## 总结

通过本教程，你已经完成了一个基础的多标签页浏览器，并掌握了 Lynxtron 桌面应用开发中的几个关键能力：

1. **自定义浏览器窗口**：通过创建无边框窗口、自定义顶部栏，以及为顶部栏添加拖拽区域，实现了浏览器的基础外观和交互框架。
2. **Lynx 与 Node.js 通信**：通过 JS Bridge 在 Lynx 侧和 Node.js 侧之间传递消息，完成了关闭、最小化和全屏切换等窗口控制能力。
3. **`<webview>` 的集成与控制**：使用 `<webview>` 加载网页内容，并通过引用调用相关方法，实现页面加载、刷新和后退等导航操作。
