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);
    // ......
}

results matching ""

    No results matching ""