API 列表

app.getVersion

功能： 获取当前 API 的版本
可用版本： ≥ v1.0.0
‎参数： 无
返回： string
注意： 异步函数，调用时需使用 await 关键字

示例:

// (onRun)
async (args, app, device, block) => {
    return await app.getVersion();
}

app.log

功能： 打印信息到 web 调试窗口，同 console.log
可用版本： ≥ v1.0.0
参数： …msgs[] 多个输出字串
返回： 无

示例:

app.log("blah-blah","no one", "nothing", 1, true);

app.warn

功能： 打印警告到 web 调试窗口，同 console.warn
可用版本： ≥ v1.0.0
参数： …msgs[] 多个输出字串
返回： 无

示例:

app.warn("something dangerous");

app.error

功能： 打印错误到 web 调试窗口，同 console.error
可用版本： ≥ v1.0.0
参数： …msgs[] 多个输出字串
返回： 无

示例:

app.error("fatal!");

app.workspace.broadcast

功能： 发起一个慧编程的广播
可用版本： ≥ v1.0.0
参数： message:string 消息名
返回： 无

示例:

// 以下模拟了积木块：广播<消息>
(args, app, device, block) => {
    app.workspace.broadcast(args.MSG);
}

app .workspace .onBroadcast

功能： 当收到慧编程的广播
可用版本： ≥ v1.0.0
参数： message:string 消息名
返回： 无

示例:

const _cancel = app.workspace.onBroadcast(msg => {
    app.log('got a message from mblock:', msg);
});
// ...
// to cancel this event handler
// _cancel()
// 以下模拟了积木块：当接收到<消息>
// onRun
(args, app, device, block) => {
    if (self._ON_BROADCAST_MSG == args.MSG) {
        self._ON_BROADCAST_MSG = null;
        return true; // true表示帽子头将会被触发
    } else {
        return false; // false表示帽子头将不会被触发
    }
}
// onAdd
(app, device, block) => {
    // 注册消息事件, 全局变量 self.__ON_BROADCAST_CANCELLER 存储 "取消注册"
    self.__ON_BROADCAST_CANCELLER = app.workspace.onBroadcast(msg => {
        self._ON_BROADCAST_MSG = msg; // 全局变量 self.__ON_BROADCAST_MSG 存储收到的广播变量
        app.workspace.runBlocks(block.opcode);
    });
}
// onRemove
(app, device, block) => {
    if (self.__ON_BROCAST_CANCELLER) self.__ON_BROCAST_CANCELLER();
}

app.workspace.getVariable

功能： 获取一个慧编程的变量值，注意，只对全局变量名有效
可用版本： ≥ v1.0.0
参数： varName:string 变量名
返回： value: string | number 变量值
注意： 异步函数，调用时需使用 await 关键字

示例:

// 以下模拟了积木块：变量
async (args, app, device, block) => {
    return await app.workspace.getVariable(args.VAR);
}

app.workspace.setVariable

功能： 设置一个慧编程的变量名和值，注意，只对全局变量名有效
可用版本： ≥ v1.0.0
参数： varName:string 变量名 value:string | number 变量值
返回： void

示例:

// 以下模拟了积木块：将<变量>设为<数值>
// onRun
async (args, app, device, block) => {
    await app.workspace.setVariable(args.VAR, args.VAL);
}

app.workspace.runBlocks

功能： 执行帽子块，注意，它不一定真正触发帽子块，在执行 .onRun 后，根据返回结果决定是否执行帽子头 (hat block) 事件触发
可用版本： ≥ v1.0.0
参数：
opcode: string 积木块 opcode
coldDown?: number 冷却时间(ms)，（可选参数，应用于触发很频繁时节流（throttle）的情况，默认值为50ms)
返回： void
注意： 异步函数，调用时需使用 await 关键字

示例:

await app.workspace.runBlocks('your_extension_id.block_id');

app.workspace.disableBlocks

功能： 禁用积木块，积木块将会置灰不可用
可用版本： ≥ v1.0.0
参数： …opcodes: string[] 积木块ID
返回： 无

示例:

app.workspace.disableBlocks('your_extension_id.block_1', 'your_extension_id.block_2', 'your_extension_id.block_3')
// you cannot use these blocks from now
// 以下积木块函数，实现了将自己置灰的功能
(args, app, device, block) => {
    app.workspace.disableBlocks(block.opcode);
}

app.workspace.enableBlocks

功能： 解禁积木块，积木块将会从置灰不可用状态到可用状态
可用版本： ≥ v1.0.0
参数： …opcodes: string[] 积木块ID
返回： 无

示例:

app.workspace.enableBlocks('your_extension_id.block_1', 'your_extension_id.block_2', 'your_extension_id.block_3')
// you can use these blocks again

app.workspace.resetEvents

功能： 重置块事件，一般在线模式连接后需要使用
可用版本： ≥ v1.0.0
参数： 无
返回： 无

示例:

function onConnect(app, device) {
  // sometimes device may disconnect by accident, then the state of mblock communicate to device is messed up, you need to reset it.
  app.workspace.resetEvents();
}

app.sendMessage

功能： 跨不同扩展的事件发送，注意，与 app.workspace.broadcast 不同，此消息不与慧编程交互；
可用版本： ≥ v1.0.0
参数：
msgName: string 消息名
…datas: any[] 消息数据
返回： 无

示例:

// in one extension/file ......
app.sendMessage("echo", 1234)；
// in other extension/file ......
app.subscribeMessage ("echo", datas=>{ 
    app.sendMessage("echo back", datas);
} )

app.subscribeMessage

功能： 跨不同扩展的事件接收，不可迭加，该次注册会把上次注册取消，可用 app.subscribeMessage(‘msgName’, null) 取消。
可用版本： ≥ v1.0.0
参数：
msgName: string 消息名
handle: function 事件响应函数
返回： 无

示例:

// in one file ......
app.sendMessage("echo", 1234)；
// in other files ......
app.subscribeMessage ("echo", (datas)=>{ 
    app.sendMessage("echo back", datas);
} )

app.receiveMessage

功能： 跨不同扩展的事件接收，异步等待 (async/await) 返回
可用版本： ≥ v1.0.0
参数： msgName: string 消息名
返回： Promise 异步返回的数据

示例:

// in one file ......
app.sendMessage("echo", ["balabala", 1234])；
// in other files ......
let datas = await app.receiveMessage("echo");
app.log('received datas of ${datas}');

target.id / device.id

功能： 获取设备ID
可用版本： ≥ v1.0.0
参数： 无
返回： string 名字

示例:

// 以下积木块函数实现返回当前角色ID
(args, app, device, block) => {
    return device.id;
}

device.isSelected

功能： 判断是否为当前选中/编辑的角色
可用版本： ≥ v1.0.0
参数： 无
返回： string 名字
注意： 异步函数，调用时需使用 await 关键字

示例:
以下积木块函数实现返回当前是否被选中。

async (args, app, device, block) => {
    return await device.isSelected();
}

device.getCode

功能： 获取当前转码（仅当可转码时）
可用版本： ≥ v1.0.0
参数： 无
返回： ICode 包含type, text字段，见示例
注意： 异步函数，调用时需使用 await 关键字

示例:

async (args, app, device, block) => {
    let {type, text} = await device.getCode();
    console.log(`code of ${type}: ${text}`);
    return text;
}

device.writeRaw

功能： 通过串口/蓝牙，向 device 写字节数据
可用版本： ≥ v1.0.0
参数：
data: number[]
channel?: string 通道名字，此为可选参数，默认为 “”
返回： 无

示例:

device.writeRaw([0xff, 0xff]);

device.setTextDecder

功能： 设置文字解码类型
可用版本： ≥ v1.0.0
参数： decoderType : ‘utf8’ | ‘ascii’ 解码类型
返回： 无

示例:

device.setTextDecoder('utf8');

device.writeText

功能： 向设备写文字数据
可用版本： ≥ v1.0.0
参数：
text: string 文字
channel?: string 通道名, 可选，默认为””
返回： Uint8Array

示例:

device.setTextDecoder('utf8');
device.writeText('text文字');

device.readText

功能： 从缓冲读入文字数据，注意，立即返回，取得已经读入缓冲的数据
可用版本： ≥ v1.0.0
参数： consume?: bool 是否从缓冲中取出并消耗，可选，默认为true
返回： string
注意： 异步函数，调用时需使用 await 关键字

示例:

device.setTextDecoder('utf8');
let text = await device.readText();
app.log('text received from device', text);

device.writeHex

功能： 向串口写字节数据，以十六进制字串表示
可用版本： ≥ v1.0.0
参数：
text: string 十六进制字串
channel?: string 通道名, 可选，默认为””
返回： 无

示例:

device.writeHex('eeff00');

device.readHex

功能： 从缓冲读入字节数据，以十六进制字串表示
可用版本： ≥ v1.0.0
参数： consume?: bool 是否从缓冲中取出并消耗，可选，默认为true
返回： string
注意： 异步函数，调用时需使用 await 关键字

示例:

let hexStr = device.readHex();
app.log('hex received from device', hexStr);

device.asyncReadProtocol

功能： 异步读取协议，当满足协议格式时返回（详细请参考如何进行协议通信.doc）
可用版本： ≥ v1.0.0
参数：
protocolName: string 协议名
pattern: any[] 匹配格式
timeout? : number 等待超时，单位ms，可选，默认 3000ms
返回： Promise
注意： 异步函数，调用时需使用 await 关键字

示例:

let datas = await device.asyncReadProtocol('your_protocol', ["ff55", 'string', 'float']);
if(datas == null) {
    app.log('receive nothing or not a valid protocol');
} else {
    app.log('receive datas, string of ${datas[0]}, float of ${datas[1]}');
}

device.asyncWriteProtocol

功能： 写数据，并包装成实际协议，注意是异步函数，需要等待（详细请参考如何进行协议通信.doc）
可用版本： ≥ v1.0.0
参数：
protocolStr: string 协议名
pattern: any[] 格式
channel?: string 通道，见device.writeRaw
返回： number[] 协议数据
注意： 异步函数，调用时需使用 await 关键字

示例:

await device.asyncWriteProtocol('your_protocol', ["ff55", ['string', 'some text'], ['float', 1.1]]);

device.subscribeReadProtocol

功能： 异步读取协议，当满足协议格式时的触发回调（详细请参考如何进行协议通信.doc）
可用版本： ≥ v1.0.0
参数：
protocolName: string 协议名
pattern: any[] 匹配格式
handler: (datas: any[]) => void 当满足协议格式时触发回调
返回： ()=>void 撤销注册

示例:

device.subscribeReadProtocol('your_protocol', ["ff55", 'string', 'float'], (datas)=>{
    app.log('receive datas, string of ${datas[0]}, float of ${datas[1]}');
});

device.isConnected

功能： 设备是否已连接
可用版本： ≥ v1.0.0
参数： 无
返回： bool
注意： 异步函数，调用时需使用 await 关键字

示例:

onConnect(app, device) {
  if(!(await device.isConnected())){
    app.error('unreachable!');
  }
}

device.isUploadMode

功能： 当前是否为上传模式，否则为在线模式
可用版本： ≥ v1.0.0
参数： 无
返回： bool
注意： 异步函数，调用时需使用 await 关键字

示例:

afterChangeUploadMode (app, device) {
  if(!(await device.isUploadMode())){
    app.error('unreachable!');
  }
}

block.opcode

功能： 积木块的 opcode (类型)
可用版本： ≥ v1.0.0
参数： 无
返回： string

示例:

onRun(args, app, device, block) {
    app.log('start to run block type of ', block.opcode);
    // ......
}

block.id

功能： 积木块的ID，相同的 opcode 的不同积木块有不同ID
可用版本： ≥ v1.0.0
参数： 无
返回： string

示例:

onRun(args, app, device, block) {
    app.log('start to run block id of ', block.id);
    // ......
}

block.arguments

功能： 积木块的参数
可用版本： ≥ v1.0.0
参数： 无
返回： any[]

示例:

onRun(args, app, device, block) {
    app.log('start to run block with arg1 of ', block.arguments.ARG1);
    // ......
}