Engine

本指南介绍如何创建、使用以及关闭 Engine。

建议你先阅读架构指南，以更好地理解 Fuzio 的整体架构设计、工作方式以及其提供的主要组件。

创建 Engine 

要创建一个新的 Engine 实例，请使用静态方法 Engine.newInstance(EngineOptions)。该方法会使用传入的选项初始化并启动 Chromium 引擎。

Java
Kotlin
var engine = Engine.newInstance(engineOptions);

val engine = Engine(engineOptions)

根据硬件性能不同，初始化过程可能需要几秒钟。我们建议不要在应用程序的 UI 线程中调用该方法，否则可能会导致整个应用在一段时间内无响应。请使用示例中描述的方式来创建 Engine。

当你创建一个新的 Engine 实例时，Fuzio 会执行以下操作：

  1. 检查运行环境，并确保其是受支持的。
  2. 查找 Chromium 二进制文件如有必要，将其解压到指定的目录。
  3. 启动 Chromium 引擎的主进程。
  4. 建立 Java 与 Chromium 主进程之间的 IPC（进程间通信）。

Engine 选项 

渲染模式 

该选项决定 Fuzio 如何在 Java 窗口中渲染网页内容。目前支持两种渲染模式：HARDWARE_ACCELERATED 和 OFF_SCREEN：

HARDWARE_ACCELERATED:

Java
Kotlin
var engine = Engine.newInstance(HARDWARE_ACCELERATED);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED)

OFF_SCREEN:

Java
Kotlin
var engine = Engine.newInstance(OFF_SCREEN);

val engine = Engine(RenderingMode.OFF_SCREEN)

有关各渲染模式的详细说明、性能表现及其限制，请参阅渲染指南。

离屏模式 

在该模式下，Chromium 使用 GPU 渲染内容，并将像素复制到内存（RAM）中。以下示例展示了如何启用离屏渲染模式：

Java
Kotlin
var engine = Engine.newInstance(OFF_SCREEN);

val engine = Engine(RenderingMode.OFF_SCREEN)

更多关于离屏渲染的性能和限制，请阅读这里。

语言 

该选项用于配置默认错误页面以及对话框中所使用的语言。默认情况下，语言会根据 Java 应用程序的默认区域设置自动确定；如果对应语言不被支持，则会使用美式英语。

当前选项允许您覆盖默认行为，并使用给定的语言配置 Chromium 引擎。例如：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .language(Language.CHINESE)
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    language = Language.CHINESE
}

在上面的代码中，我们使用中文配置了 Engine。如果 Fuzio 无法加载网页，将显示中文错误页面：

Error Page

I18N 国际化 

当浏览本地文件系统时，库支持 I18N 国际化：

浏览本地文件系统

用户数据目录 

该选项表示一个绝对路径，用于存储用户的 Profile 及其相关数据，包括缓存、Cookie、历史记录、GPU 缓存、本地存储、访问过的链接、Web 数据、拼写检查词典文件等。

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .userDataDir(Paths.get("/Users/Me/.fuzio"))
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    userDataDir = Path("/Users/Me/.fuzio")
}

同一个用户数据目录不能同时被多个 Engine 实例使用（无论是在同一个还是不同的 Java 应用中）。如果目录已被其他 Engine 使用，则创建 Engine 将失败。

该目录不能位于网络驱动器上。

如果在创建 Engine 时未指定用户数据目录，Engine 将在系统临时目录中自动创建一个目录并使用它。在关闭 Engine 时，该临时目录会被自动删除。

无痕模式 

该选项用于指示是否为默认 Profile 启用无痕模式。在该模式下，浏览历史、Cookie、站点数据等信息仅存储在内存中，并会在删除 Profile 或关闭 Engine 时释放。

默认情况下，无痕模式处于禁用状态。

下面的示例演示了如何启用无痕模式：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .enableIncognito()
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    incognitoEnabled = true
}

用户代理 

使用该选项可以配置默认的用户代理（User Agent）字符串。例如：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .userAgent("<user-agent>")
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    userAgent = UserAgent("<user-agent>")
}

你可以在每个 Browser 实例中覆盖默认的 User Agent 字符串。

远程调试端口 

Chrome 开发者工具协议。

下面的示例演示了如何设置端口号：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .addSwitch("--remote-allow-origins=http://localhost:9222")
                .remoteDebuggingPort(9222)
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    switches = listOf("--remote-allow-origins=http://localhost:9222")
    remoteDebuggingPort = 9222
}

要检查在 Fuzio 中加载的网页，你可以使用以下方式：

Chrome Inspect
打开 Google Chrome 并访问 chrome://inspect 来检查网页。

Chrome Inspect

远程调试 URL
获取加载了目标网页的 Browser 实例的远程调试 URL，并在另一个 Browser 实例中打开它。

远程调试 Port

你也可以随时使用内置 DevTools 来检查网页。

禁用触控菜单 

在 Windows 10 触控设备上，长按可能会弹出触控上下文菜单。

下面的代码片段演示了如何禁用该触控菜单：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .disableTouchMenu()
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    touchMenuDisabled = true
}

Chromium 二进制文件目录 

使用该选项可以指定一个绝对路径或相对路径，用于定义 Chromium 二进制文件所在的目录，或指定其需要被解压到的目录。例如：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .chromiumDir(Paths.get("/Users/Me/.fuzio/chromium"))
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    chromiumDir = Path("/Users/Me/.fuzio/chromium")
}

另请参阅 Chromium 二进制文件位置。

Chromium 参数 

Chromium 支持命令行参数（switches），用于改变其行为、启用调试或开启实验性功能。

要使用所需参数配置 Chromium，可使用以下 API：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .addSwitch("--<switch-name>")
                .addSwitch("--<switch-name>=<switch-value>")
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    switches = listOf(
        "--<switch-name>",
        "--<switch-name>=<switch-value>"
    )
}

并非所有 Chromium 参数都受 Fuzio 支持，因此无法保证传入的参数一定生效，或不会导致错误。我们建议优先通过 Engine 选项来配置 Chromium，而不是依赖参数。

Google API 

Chromium 的某些功能（如地理位置、拼写检查、语音等）会使用 Google API。要访问这些 API，需要提供 API Key、OAuth 2.0 客户端 ID 以及客户端密钥。要获取 API Key，请按照此说明操作。

要提供 API Key、客户端 ID 和客户端密钥，请使用以下代码：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(HARDWARE_ACCELERATED)
                .googleApiKey("<api-key>")
                .googleDefaultClientId("<client-id>")
                .googleDefaultClientSecret("<client-secret>")
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    google {
        apiKey = GoogleApiKey("<api-key>")
        defaultClientId = GoogleClientId("<client-id>")
        defaultClientSecret = GoogleClientSecret("<client-secret>")
    }
}

配置 API Key 是可选的。若不进行配置，则依赖 Google 服务的某些 API 将无法使用。

专有功能 

该库允许通过以下选项启用专有功能，例如 H.264/AAC 编解码器：

Java
Kotlin
var engine = Engine.newInstance(
        EngineOptions.newBuilder(renderingMode)
                .enableProprietaryFeature(proprietaryFeature)
                .build()
);

val engine = Engine(RenderingMode.HARDWARE_ACCELERATED) {
    proprietaryFeatures = setOf(proprietaryFeature)
}

时区 

Web 开发者可以通过 JavaScript 的 Intl 对象获取浏览器的时区。默认情况下，Chromium 使用系统时区。

该 Engine 选项允许你覆盖 Chromium 所使用的时区：

Java
Kotlin
var timeZone = ZoneId.of("Asia/Shanghai");
var engine = Engine.newInstance(
        EngineOptions.newBuilder(renderingMode)
                .timeZone(timeZone)
                .build()
);

val timeZone = ZoneId.of("Asia/Shanghai")
val engine = Engine.newInstance(
      EngineOptions.newBuilder(renderingMode)
                    .timeZone(timeZone)
                    .build())

关闭 Engine 

Engine 会分配内存和系统资源，这些资源必须被释放。因此，当 Engine 不再需要时，必须通过 Engine.close() 方法关闭它，以便关闭原生 Chromium 进程，并释放所有已分配的内存和系统资源。例如：

Java
Kotlin
var engine = Engine.newInstance(engineOptions);
...
engine.close();

val engine = Engine(engineOptions)
...
engine.close()

任何尝试使用已关闭的 Engine 的操作都会导致 IllegalStateException。

要检查 Engine 是否已关闭，请使用以下方法：

Java
Kotlin
var closed = engine.isClosed();

val closed = engine.isClosed

主题 

你可以将 Fuzio 配置为使用深色、浅色或系统主题来显示网页内容以及原生对话框，例如打印预览、选择来源、DevTools 等。

深色/浅色主题

要获取当前使用的主题，请使用 Engine.theme() 方法：

Java
Kotlin
Theme theme = engine.theme();
if (theme == Theme.DARK) {
    // 该 engine 及其所有浏览器均使用深色主题。
}
if (theme == Theme.LIGHT) {
    // 该 engine 及其所有浏览器均使用浅色主题。
}
if (theme == Theme.SYSTEM) {
    // 主题继承自操作系统。
}

val theme = engine.theme()
when (theme) {
    Theme.DARK -> {
        // 该 engine 及其所有浏览器均使用深色主题。
    }
    Theme.LIGHT -> {
        // 该 engine 及其所有浏览器均使用浅色主题。
    }
    Theme.SYSTEM -> {
        // 主题继承自操作系统。
    }
}

默认情况下，Fuzio 使用操作系统中设置的主题。当操作系统在深色与浅色主题之间切换时，Fuzio 会自动切换到相应主题。

若要手动在深色与浅色主题之间切换，可使用以下方式：

Java
Kotlin
engine.setTheme(Theme.DARK);
engine.setTheme(Theme.LIGHT);
engine.setTheme(Theme.SYSTEM);

engine.setTheme(Theme.DARK)
engine.setTheme(Theme.LIGHT)
engine.setTheme(Theme.SYSTEM)

在无痕模式下，调用 Engine.setTheme() 方法不会改变页面的实际颜色，但会改变 Engine.theme() 返回的值。

Engine 事件 

Engine 关闭 

要在 Engine 被关闭时接收通知，请使用 EngineClosed 事件：

Java
Kotlin
engine.on(EngineClosed.class, event -> {
});

engine.subscribe<EngineClosed> { event -> }

Engine 崩溃 

要在 Chromium 引擎发生内部错误导致 Engine 崩溃时接收通知，请使用 EngineCrashed 事件：

Java
Kotlin
engine.on(EngineCrashed.class, event -> {
    var exitCode = event.exitCode();
    // 你可以在此处重新创建 engine 和 browser 实例。
    // 请确保对新 engine 使用相同的选项，并在新 engine 上也注册 EngineCrashed 事件处理器。
});

engine.subscribe<EngineCrashed> { event ->
    val exitCode = event.exitCode()
    // 你可以在此处重新创建 engine 和 browser 实例。
    // 请确保对新 engine 使用相同的选项，并在新 engine 上也注册 EngineCrashed 事件处理器。
}

引擎崩溃后，别忘了收集崩溃转储和日志，因为它们包含关键的调试信息，我们需要这些信息来分析崩溃原因。

Fuzio 与 Chromium 版本 

在运行时，你可能需要获取所使用的 Fuzio 与 Chromium 版本信息。该信息可通过 VersionInfo 类获取：

Java
Kotlin
import tech.fuzio.VersionInfo;
...
var productVersion = VersionInfo.version();
var chromiumVersion = VersionInfo.chromiumVersion();

import tech.fuzio.VersionInfo
...
val productVersion = VersionInfo.version()
val chromiumVersion = VersionInfo.chromiumVersion()

返回的 Fuzio 版本格式为 2026.1.0，其中可能包含数字、点号、短横线以及字母。

返回的 Chromium 版本格式为 147.0.7727.56，其中包含用点号分隔的数字。

微信咨询

即库客服

微信公众号二维码

技术客服

微信公众号二维码