ROBOMATION LAB
한국어EnglishEspañolFrançaisDeutschItalianoPortuguês日本語繁體中文NederlandsРусскийSvenskaPolskiTürkçeBahasa IndonesiaTiếng ViệtไทยDanskSuomiNorsk

简体中文

한국어
English
Español
Français
Deutsch
Italiano
Português
日本語
繁體中文
Nederlands
Русский
Svenska
Polski
Türkçe
Bahasa Indonesia
Tiếng Việt
ไทย
Dansk
Suomi
Norsk

外观

编程规则 ​

本文档说明在 RobomationLAB 中进行机器人编程时应遵守的编程规则。

参考: 脚本编程 专用于 Python，积木会 1 对 1 转换为使用 robomation Python 包的 Python 代码。

顺序说明: 按共通的核心规则(1~2) → 积木代码规则(3~5) → Python 脚本代码规则(6~11) 的顺序整理。积木代码和 Python 代码的生成都要作为重点遵守。


1. 积木 ↔ Python 1 对 1 转换的限制 ​

积木编程编辑器和 Python 编程编辑器 1 对 1 对应，并实时双向转换。

  • 积木 → Python: 积木总是会转换为正确的 Python 代码。
  • Python → 积木: 只对 能用积木表示的代码 进行转换。

因此，在 Python 编辑器中编写下面这样的代码时，可能无法从 Python 切换到积木编程编辑器，
这时会一起显示切换失败的原因。

  1. 有 Python 语法错误的代码
  2. 使用了不与积木对应（转换规则中未定义）的函数、方法、语法的代码

要保持能正常切换到积木编程编辑器，
必须在本文档和各机器人文档中定义的类、方法、函数以及支持的语法范围内编写代码。


2. 代码提示规则 ​

只能使用 robomation Python API 手册 和 积木 ↔ Python 转换规则文档 中明确列出的类、方法和函数。
控制机器人时，严格禁止创建并使用上述文档中未定义的新的机器人控制方法。 不过，用户要求创建新函数时是允许的。

上述文档中的转换示例里没有出现的临时变量（例: 除存放机器人实例的变量以外的额外变量）的声明，只有在用户要求创建变量时才能创建。
另外，方法的实参必须写成字面量。

python
# 正确的例子
hamster_s.set_wheel_speed('both', 100)

# 错误的例子 - 使用了 API 手册中未列出的函数
hamster_s.set_wheel('both', 100)

# 错误的例子 - 声明任意变量
SPEED = 100
hamster_s.set_wheel_speed('both', SPEED)

3. 积木代码的基本结构 ​

提示积木代码时，必须始终把作为程序入口的最上层函数积木 setup 函数和 loop 函数作为基本结构包含进来。
加上这条规则后，之后所有的积木代码都会具有下面这样的基本结构。

积木结构 (Block Composer)提示方式（文本形式）
setup 函数setup 函数
(内部的积木)(内部的积木)
loop 函数loop 函数
(内部的积木)(内部的积木)

4. 积木代码的格式（换行和缩进规则） ​

  • 最上层的积木（setup 函数、loop 函数等）左对齐。
  • 每个命令积木必须用换行符分隔，一行只输出一个积木。
  • 内部有执行区域的积木（如果、重复、函数定义等）内部包含的下层积木要使用缩进，清楚地表现层次结构。

5. 内部积木和条件的表达规则 ​

下拉菜单的选择值或输入值相当于积木的功能性实参(Argument)，用方括号([])在积木文字中该值所在的位置直接插入来表达。
这样做是为了把积木固有的文字和用户选择、输入的值结合起来，在视觉上再现积木。

所有积木代码都必须以包含积木固有名称、下拉菜单选择值以及用户输入值（全部使用方括号([])）的形式提示，
用文本尽可能贴近地再现实际 Block Composer 积木的样子。

积木结构 (Block Composer)提示方式（文本形式）
如果 [条件] 执行 [命令] 否则 [命令]如果 [条件] 执行 [命令] 否则 [命令]
RaccoonBot: 设为 [速度] 控制模式RaccoonBot: 设为 [速度] 控制模式
RaccoonBot: 将关节 [1] 的速度设为 [100]RaccoonBot: 将关节 [1] 的速度设为 [100]

6. 脚本代码的基本结构 ​

提示脚本代码(Python)时，必须始终把作为程序入口的函数 setup() 和 loop() 作为基本结构包含进来。
另外，为了能使用控制机器人所需的类和实用工具，要在代码最上方包含 from robomation import *，并把要使用的机器人声明为实例。
加上这条规则后，之后所有的脚本代码(Python)都会具有下面这样的基本结构。

python
# Python 代码的基本结构
from robomation import *

# (如果有要使用的机器人，就声明为实例，示例)
hamster_s = HamsterS(0)

# 在此处放置仅运行一次的初始化代码：
def setup():
    pass

# 在此处放置重复运行的控制代码：
def loop():
    pass

7. 脚本代码的格式（换行和缩进规则） ​

  • 最上层的函数（setup, loop 等）左对齐。
  • 换行时产生的缩进必须以 1 个制表符(\t) 为基准。（与编辑器的缩进基准相同）

8. 机器人控制规则（实例 / 方法） ​

控制机器人时，必须遵守下面这些规则。

  1. 在代码最上方包含 from robomation import *。
  2. 把要使用的机器人声明为实例。变量名使用各机器人既定的默认变量名，索引从 0 开始分配。
  3. 调用所声明实例的方法来控制机器人。
python
from robomation import *

hamster_s = HamsterS(0)

def setup():
    hamster_s.set_wheel_speed('both', 50)

def loop():
    pass

使用同一种机器人的多台时，把索引按 0, 1, 2 … 递增来声明。(例: hamster_s = HamsterS(0), hamster_s_1 = HamsterS(1))

机器人的轮速度设置、移动等操作，会在方法内部自动处理所需的初始化（例: 清理之前的移动命令），因此不需要另外编写前置的初始化代码。


9. 实用函数的调用规则 ​

延时、播放声音、输出日志、颜色等共通的实用功能，通过 Utils 类的方法调用。

python
Utils.wait(1)  # (seconds)
Utils.play_sound('', 100, False)
Utils.log(0, '', '')

详细的实用函数列表请参阅下面的文档。


10. 优先使用机器人专用方法的规则 ​

控制机器人硬件（轮速度、LED、声音等）时，
必须优先使用机器人（例:「HamsterS」）实例的专用方法，而不是共通的实用函数。

例如，需要用机器人发出声音时，
必须优先使用「HamsterS」实例的 sound_clip() 方法，而不是实用函数 Utils.play_sound()。

python
# 通过 HamsterS 机器人发出声音。(推荐)
hamster_s.sound_clip('beep')

# 通过 PC / 平板 / 移动设备发出声音。(不推荐)
Utils.play_sound('beep', 100, False)

11. Import 规则 ​

编写 Python 代码时，只 import 运行代码所需的模块。

  • 为了控制机器人，默认在代码最上方包含 from robomation import *。
  • 使用 math. 的代码会自动添加 import math，使用 random. 的代码会自动添加 import random。
  • 其他不必要的模块不要 import。

© 2026 Robomation. All rights reserved.