zero-native中文文档

Appearance

扩展系统 (Extensions) ​

ModuleRegistry 提供了一个基于钩子（hook）的扩展系统，用于向运行时动态添加模块化的扩展能力。

模块结构 (Module structure) ​

每个模块均包含一个描述信息块（info block）、一个指向模块实例状态的上下文指针（context pointer）以及可选的生命周期钩子（lifecycle hooks）：

zig
const MyModule = struct {
    data: u32 = 0,

    fn start(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        self.data = 42;
    }

    fn command(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext, cmd: zero_native.extensions.Command) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        if (std.mem.eql(u8, cmd.name, "reset")) self.data = 0;
    }
};

注册模块 (Registering modules) ​

zig
var my_module = MyModule{};
const caps = [_]zero_native.extensions.Capability{.{ .kind = .native_module }};
const modules = [_]zero_native.extensions.Module{.{
    .info = .{ .id = 1, .name = "my-module", .capabilities = &caps },
    .context = &my_module,
    .hooks = .{ .start_fn = MyModule.start, .command_fn = MyModule.command },
}};
const registry = zero_native.extensions.ModuleRegistry{ .modules = &modules };

var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .extensions = registry,
});

模块字段说明 ​

字段名类型描述
info.idu64唯一的数字标识符（在注册校验时若检测到重复的 ID 则会被拒绝）。
info.name[]const u8易于阅读的模块名称。
info.capabilities[]const Capability该模块所提供的一组能力能力声明。
context*anyopaque指向模块自定义状态的类型擦除指针（Opaque pointer）。
hooks.start_fnoptional当运行时启动时被调用。
hooks.stop_fnoptional当运行时停止时被调用（以模块注册的相反顺序进行逆序调用）。
hooks.command_fnoptional当有命令分发给扩展模块时被调用。

注册表方法 (Registry methods) ​

方法描述
validate()检查并校验是否存在重复的模块 ID。
startAll(runtime)依次调用所有模块的 start_fn 启动钩子。
stopAll(runtime)逆序调用所有模块的 stop_fn 停止钩子（先进后出原则）。
dispatchCommand(runtime, command)向所有注册的扩展模块分发并调用对应的 command_fn。
hasCapability(kind)检查是否有任何已注册的扩展模块声明并提供了指定的某种能力。

能力类型 (Capability kinds) ​

能力种类描述
native_module原生 Zig 模块。
webviewWebView 页面渲染能力。
js_bridgeJavaScript 桥接通道能力。
filesystem本地文件系统访问权限。
network网络访问权限。
clipboard剪贴板读写访问权限。
custom自定义能力（带有一个额外的 name 名称字段）。

这些能力类型直接映射到 app.zon 中的 capabilities 声明列表中。运行时可以使用 registry.hasCapability(.filesystem) 来动态查询是否有任何扩展模块为应用提供了指定的能力（例如 filesystem）。

原生 JS 引擎（实验性特性） ​

js 模块提供了一个底层的抽象层，用于从原生 Zig 直接调用原生 JavaScript 引擎。这与 WebView 的桥接器是各自独立的，主要用于未来的原生底层模块的集成开发。

类型描述
Value标记联合体（Tagged union），可表示为：null、布尔值（boolean）、数字（number）、字符串（string）。
Call代表一个函数调用，包含：调用模块（module）、调用函数（function）以及参数（args）。
Bridge用于通过 RuntimeHooks 来校验并分发原生函数调用。
NullEngine引擎不可用时的预留存根（Stub），调用时始终返回 EngineUnavailable 错误。