bindings.json

bindings.json

AI 原文

bindings.json

功能

bindings.json 描述扩展对 BT 脚本公开的调用表面。它不写业务逻辑，只声明入口函数、扩展对象、对象方法、参数类型、返回类型和对象生命周期语义。

脚本能调用什么，完全由 bindings.json 决定；扩展后端必须提供与 bindings 对应的实现。

语法

参数

字段说明
api_version必须和 manifest.api_version 一致，使用 1。
functions公开入口函数列表，至少需要一个入口。
functions[].name脚本里看到的全局入口名，例如 calc。
functions[].id后端调用 ID，WASM 扩展用它分发到具体 handler。
functions[].params参数列表。
functions[].returns返回类型，可以是原始类型或 objects 中声明的对象类型。
objects扩展对象类型列表。
objects[].name对象类型名，必须大写字母开头，例如 Calc。
objects[].type_id对象类型 ID，不能为 0。
objects[].methods对象方法列表。
methods[].lifecycle方法生命周期，默认 call，可写 dispose。

参数类型

bindings 支持以下参数类型：

类型说明
emptyBT 的 empty。
nullBT 的 null。
bool布尔值。
int整数。
float浮点数。
string字符串。
bytesBytes 二进制字节。
array数组。
object普通对象。

返回类型可以使用这些原始类型，也可以使用 objects 中已声明的对象类型名。

返回值

bindings 本身没有运行时返回值。扩展实际返回值由 returns 字段约束：如果写原始类型，运行时会校验真实返回值类型；如果写对象类型名，运行时会要求返回对应扩展对象。

参数 role

参数默认是普通值：

如果参数是给 WASM 扩展使用的路径，可以声明 role：

role说明
value普通值，不做路径处理。
path_read读取文件路径，要求 type 为 string，并声明 fs_read。
path_write写入文件路径，要求 type 为 string，并声明 fs_write。
path_dir目录路径，要求 type 为 string，并声明 fs_read 或 fs_write。

代码示例

上面的 bindings 会让脚本获得这样的调用体验：

注意事项

  • 入口名、方法名、参数名必须使用 snake_case，不能以下划线开头或结尾。
  • id 在同一个 bindings 文件中不能重复，且不能为 0。
  • 对象 type_id 不能为 0，同一个扩展内不能重复。
  • lifecycle: "dispose" 只能用于 close 或 dispose 方法；方法不能有参数，返回类型必须是原始类型。
  • 纯 BT 扩展要求 bindings 中的入口函数和对象方法在 src/lib.bt 中存在同名实现。