# Scratchblocks 官方语法完整参考文档

> **官方文档来源**：https://en.scratch-wiki.info/wiki/Block_Plugin/Syntax
>
> **重要提醒**：本文档记录了所有Scratch积木的标准写法，生成代码时必须严格遵循！

---

##  目录

1. [参数类型](#1-参数类型)
2. [事件积木](#2-事件积木hat-blocks)
3. [控制结构（C型积木）](#3-控制结构c型积木)
4. [if-else 条件判断](#4-if-else-条件判断)
5. [变量操作](#5-变量操作)
6. [运算积木](#6-运算积木)
7. [等待和说话](#7-等待和说话)
8. [画笔积木](#8-画笔积木)
9. [外观积木](#9-外观积木)
10. [运动积木](#10-运动积木)
11. [列表操作](#11-列表操作)
12. [广播消息](#12-广播消息)
13. [完整示例](#13-完整示例)
14. [常见错误对照表](#14-常见错误对照表)

---

## 1. 参数类型

### 1.1 数值参数（Numerical Insert）

使用**圆括号** `(数字)`

```scratchblocks
move (10) steps
```

**示例**：
- `move (10) steps` - 移动10步
- `turn cw (15) degrees` - 旋转15度
- `wait (2) secs` - 等待2秒
- `change [分数 v] by (10)` - 分数增加10

### 1.2 文本参数（String Insert）

使用**方括号** `[文本]`

```scratchblocks
say [Hi]
```

**示例**：
- `say [你好]` - 说"你好"
- `think [让我想想]` - 思考"让我想想"
- `say [准备开始] for (2) secs` - 说"准备开始"2秒

### 1.3 布尔条件（Block Insert - Boolean）

使用**尖括号** `<条件>`

```scratchblocks
if <mouse down?> then
    change [mouse clicks v] by (1)
end
```

**示例**：
- `<mouse down?>` - 鼠标按下
- `<touching [mouse-pointer v]?>` - 碰到鼠标指针
- `<touching [edge v]?>` - 碰到边缘
- `<key [space v] pressed?>` - 按下空格键
- `<([分数 v]) > [90]>` - 分数大于90

### 1.4 报告器变量（Reporter Variable）

使用**圆括号** `(变量名)` - 注意：变量名不带方括号！

```scratchblocks
say (分数)
set [n v] to (answer)
```

**示例**：
- `(costume [number v])` - 造型编号（内置函数需要方括号）
- `(answer)` - 回答
- `(random (1) to (10))` - 1到10的随机数
- `(n)` - 变量n的值 ✓ 官方标准写法
- `(分数)` - 变量分数的值 ✓ 官方标准写法
- `([分数 v])` - 变量分数的值（也可以，但官方示例用的是上面那种）

### 1.5 颜色输入（Color Input）

使用**方括号**包含十六进制颜色代码 `[颜色]`

```scratchblocks
set pen color to [#1540bf]
```

**示例**：
- `[#1540bf]` - 6位十六进制
- `[#0f0]` - 3位十六进制（简写）
- `set pen color to [#FF0000]` - 设置画笔颜色为红色
- `<touching color [#FF0000]?>` - 碰到红色

### 1.6 下拉菜单（Dropdown List）

**方形下拉菜单**：使用 `[选项 v]`

```scratchblocks
stop [all v]
```

**圆形下拉菜单**：使用 `(选项 v)` 或 `[选项 v]`

```scratchblocks
broadcast (start v)
```

**示例**：
- `stop [all v]` - 停止全部
- `stop [this script v]` - 停止这个脚本
- `[mouse-pointer v]` - 鼠标指针
- `[edge v]` - 边缘
- `[space v]` - 空格键
- `[分数 v]` - 变量"分数"
- `(start v)` - 消息"开始"

---

## 2. 事件积木（Hat Blocks）

### 2.1 绿旗点击（3种写法均可）

```scratchblocks
when green flag clicked
when gf clicked
when flag clicked
```

### 2.2 键盘事件

```scratchblocks
when [space v] key pressed
```

### 2.3 角色被点击

```scratchblocks
when this sprite clicked
```

---

## 3. 控制结构（C型积木）

### 3.1 基本规则

- C型积木必须用 `end` 结尾
- 脚本最后的C积木可以自动闭合（省略end）
- 嵌套代码使用**4个空格**缩进

### 3.2 repeat 循环

```scratchblocks
repeat (10)
    move (5) steps
    stamp
end
```

**示例**：
```scratchblocks
repeat (3)
    move (10) steps
    turn cw (15) degrees
end
```

### 3.3 forever 无限循环

```scratchblocks
forever
    move (10) steps
    stamp
end
```

**示例**：
```scratchblocks
forever
    turn cw (15) degrees
    say [Hello!] for (2) secs
end
```

### 3.4 repeat until 重复直到

```scratchblocks
repeat until <(分数) > (90)>
    change [分数 v] by (10)
end
```

**示例**：
```scratchblocks
set [分数 v] to (0)
repeat until <(分数) > (90)>
    change [分数 v] by (10)
end
say (分数)
```

---

## 4. if-else 条件判断

### 4.1 简单 if 语句

**格式**：
```
if <条件> then
    [代码]
end
```

**示例**：
```scratchblocks
if <mouse down?> then
    change [mouse clicks v] by (1)
end
```

```scratchblocks
if <touching [mouse-pointer v]?> then
    say [碰到了！] for (2) secs
end
```

### 4.2 if-else 语句

**格式**：
```
if <条件> then
    [then分支代码]
else
    [else分支代码]
end
```

**示例**：
```scratchblocks
if <touching [mouse-pointer v]?> then
    say [碰到了！] for (2) secs
else
    say [没碰到] for (2) secs
end
```

### 4.3 嵌套 if-else（重要！）

**Scratch不支持 `else if`，必须使用嵌套！**

**格式**：
```
if <条件1> then
    [代码1]
else
    if <条件2> then
        [代码2]
    else
        [代码3]
    end
end
```

**示例 - 分数等级判断**：
```scratchblocks
if <(分数) > (90)> then
    say [优秀] for (2) secs
else
    if <(分数) > (60)> then
        say [及格] for (2) secs
    else
        say [不及格] for (2) secs
    end
end
```

### 4.4 条件组合

**AND 逻辑**：
```scratchblocks
if <<mouse down?> and <(分数) > (10)>> then
    say [太棒了！] for (2) secs
end
```

**OR 逻辑**：
```scratchblocks
if <<key [space v] pressed?> or <touching [edge v]?>> then
    say [触发！] for (2) secs
end
```

### 4.5 复杂条件示例

```scratchblocks
if <<mouse down?> and <(costume [number v]) = (1)>> then
    stamp
end
```

```scratchblocks
if <((n) mod (2)) = (0)> then
    set [n v] to ((n) / (2))
else
    set [n v] to (((3) * (n)) + (1))
end
```

---

## 5. 变量操作

### 5.1 set to（赋值）

**格式**：`set [变量 v] to (值)`

**关键**：值使用**圆括号**

```scratchblocks
set [n v] to (answer)
set [i v] to (0)
set [分数 v] to (100)
```

### 5.2 change by（增加/减少）

**格式**：`change [变量 v] by (数值)`

```scratchblocks
change [i v] by (1)
change [分数 v] by (10)
change [分数 v] by (-5)
```

### 5.3 show/hide 变量

```scratchblocks
show variable [分数 v]
hide variable [分数 v]
```

---

## 6. 运算积木

### 6.1 比较运算

```scratchblocks
<(n) = (1)>                    // 等于
<(分数) > (90)>                 // 大于
<(分数) < (60)>                 // 小于
<(分数) >= (90)>                // 大于等于
<(分数) <= (60)>                // 小于等于
```

### 6.2 布尔运算

```scratchblocks
<<条件1> and <条件2>>          // 且
<<条件1> or <条件2>>           // 或
<not <条件>>                   // 非
```

### 6.3 模运算

```scratchblocks
((n) mod (2))                  // n除以2的余数
<((n) mod (2)) = (0)>          // 判断是否为偶数
```

### 6.4 数学运算

```scratchblocks
((n) / (2))                    // 除法
(((3) * (n)) + (1))            // 混合运算
((n) + (10))                   // 加法
((n) - (5))                    // 减法
```

### 6.5 随机数

```scratchblocks
(pick random (1) to (10))       // 1到10的随机数
(answer)                        // 用户输入
```

---

## 7. 等待和说话

### 7.1 wait 等待

```scratchblocks
wait (1) secs
wait (0.5) secs
```

### 7.2 say 说话

```scratchblocks
say [你好]
say (变量)
say [你好] for (2) secs
say (分数) for (1) secs
```

---

## 8. 画笔积木

### 8.1 基本画笔

```scratchblocks
pen down
pen up
clear
```

### 8.2 画笔颜色

```scratchblocks
set pen color to [#FF0000]
set pen color to (150)
```

### 8.3 画笔大小

```scratchblocks
set pen size to (3)
```

### 8.4 画笔透明度

```scratchblocks
set pen shade to (50)
```

---

## 9. 外观积木

### 9.1 造型切换

```scratchblocks
next costume
switch costume to [造型1 v]
switch backdrop to [背景1 v]
```

### 9.2 造型报告器

```scratchblocks
(costume [number v])           // 当前造型编号
(costume [name v])             // 当前造型名称
(backdrop [name v])            // 当前背景名称
```

---

## 10. 运动积木

### 10.1 移动和旋转

```scratchblocks
move (10) steps
turn cw (15) degrees
turn ccw (15) degrees
turn right (15) degrees
turn left (15) degrees
```

### 10.2 坐标控制

```scratchblocks
go to x: (0) y: (0)
go to [mouse-pointer v]
glide (1) secs to x: (100) y: (100)
change x by (10)
change y by (10)
```

### 10.3 边缘检测

```scratchblocks
<touching [mouse-pointer v]?>
<touching [edge v]?>
<bouncing off edge>
```

---

## 11. 列表操作

### 11.1 添加删除

```scratchblocks
add [苹果] to [水果 v]
delete (1) of [水果 v]
delete all of [水果 v]
```

### 11.2 插入替换

```scratchblocks
insert [香蕉] at (1) of [水果 v]
replace item (1) of [水果 v] with [葡萄]
```

### 11.3 列表报告器

```scratchblocks
(item (1) of [水果 v])          // 获取第1项
(length of [水果 v])             // 列表长度
<[水果 v] contains [苹果]?>      // 是否包含某项
```

---

## 12. 广播消息

### 12.1 发送广播

```scratchblocks
broadcast (start v)
broadcast [开始 v] and wait
```

### 12.2 接收广播

```scratchblocks
when I receive [start v]
```

---

## 13. 完整示例

### 13.1 基础示例

```scratchblocks
when green flag clicked
forever
    turn cw (15) degrees
    say [Hello!] for (2) secs
    if <mouse down?> then
        change [mouse clicks v] by (1)
    end
end
```

### 13.2 嵌套循环示例

```scratchblocks
when flag clicked
repeat (3)
    repeat (4)
        move (10) steps
    end
end
```

### 13.3 条件与循环组合

```scratchblocks
when flag clicked
set [计数 v] to (0)
repeat (10)
    if <touching color [#FF0000]?> then
        change [计数 v] by (1)
    end
    wait (0.5) secs
end
```

### 13.4 Collatz猜想（官方标准示例）

```scratchblocks
when gf clicked
ask [n=] and wait
set [n v] to (answer)
set [i v] to (0)
repeat until <(n) = (1)>
    if <((n) mod (2)) = (0)> then
        set [n v] to ((n) / (2))
    else
        set [n v] to (((3) * (n)) + (1))
    end
    change [i v] by (1)
end
say (i)
```

### 13.5 多脚本示例

```scratchblocks
when flag clicked
forever
    move (10) steps
end

when flag clicked
forever
    turn cw (15) degrees
end
```

### 13.6 画笔绘制正方形

```scratchblocks
when flag clicked
clear
pen down
set pen color to [#FF0000]
repeat (4)
    move (80) steps
    turn cw (90) degrees
end
pen up
```

### 13.7 键盘控制

```scratchblocks
when flag clicked
forever
    if <key [space v] pressed?> then
        change y by (10)
    end
end
```

---

## 14. 常见错误对照表

### 14.1 参数括号错误

| 类型 | ✅ 正确 | ❌ 错误 |
|------|---------|---------|
| 数值参数 | `move (10) steps` | `move 10 steps` |
| 文本参数 | `say [你好]` | `say 你好` |
| 变量值 | `(分数)` 或 `([分数 v])` | `分数` |
| 布尔条件 | `if <条件> then` | `if 条件 then` |

### 14.2 set to 错误（重要！）

| ✅ 正确 | ❌ 错误 |
|---------|---------|
| `set [分数 v] to (90)` | `set [分数 v] to [90]` |
| `set [n v] to (answer)` | `set [n v] to answer` |
| `set [n v] to ((n) / (2))` | `set [n v] to ([n] / [2])` |

### 14.3 条件比较错误（重要！）

| ✅ 正确 | ❌ 错误 |
|---------|---------|
| `<(分数) > (90)>` | `<([分数 v]) > (90)>` 或 `<[分数 v] > (90)>` |
| `<(n) = (1)>` | `<n = 1>` |
| `<((n) mod (2)) = (0)>` | `<(n) mod (2) = 0>` |

### 14.4 旋转指令错误

| ✅ 正确 | ❌ 错误 |
|---------|---------|
| `turn cw (15) degrees` | `turn clockwise (15) degrees` |
| `turn ccw (15) degrees` | `turn counterclockwise (15) degrees` |
| `turn right (15) degrees` | `turn anticlockwise (15) degrees` |
| `turn left (15) degrees` | 无 |

### 14.5 时间单位

| ✅ 正确 | ❌ 错误 |
|---------|---------|
| `wait (2) secs` | `wait (2) seconds` |
| `say [你好] for (2) secs` | `say [你好] for (2) seconds` |

### 14.6 控制结构错误

| ✅ 正确 | ❌ 错误 |
|---------|---------|
| `repeat (10)\n    代码\nend` | `repeat (10)\n    代码`（缺少end） |
| `if <条件> then\n    代码\nend` | `if <条件> then\n    代码`（缺少end） |
| 4个空格缩进 | 2个空格缩进 |

### 14.7 if-else 错误

| ✅ 正确 | ❌ 错误 |
|---------|---------|
| `if <条件> then` | `if then`（缺少条件） |
| `if <条件> then\n    代码\nelse\n    代码\nend` | `if <条件> then else`（都在一行） |
| 嵌套if-else | `else if`（不支持） |

### 14.8 绿旗事件错误

| ✅ 正确 | ❌ 错误 |
|---------|---------|
| `when green flag clicked` | `when flag click` |
| `when gf clicked` | `when greenflag clicked` |
| `when flag clicked` | 无 |

---

## 15. JSON中的代码格式

在JSON配置文件中，代码需要正确处理换行和转义：

### 15.1 换行符

使用 `\n`（单反斜杠）表示换行：

```json
"title": "题目<br/>[scratchblocks]when flag clicked\nmove (10) steps\nend[/scratchblocks]"
```

### 15.2 引号转义

使用 `\"` 转义双引号：

```json
"title": "说\"你好\"2秒"
```

### 15.3 完整示例

```json
{
    "title": "分析代码：<br/>[scratchblocks]when flag clicked\nif <touching [mouse-pointer v]?> then\n    say [碰到了！] for (2) secs\nelse\n    say [没碰到] for (2) secs\nend[/scratchblocks]",
    "analyzeContent": "<p>考点：条件判断</p><p>解析：if-else根据条件选择执行分支。</p>"
}
```

---

## 16. 快速检查清单

生成代码前，逐项检查：

- [ ] 数值参数使用圆括号 `(10)`
- [ ] 文本参数使用方括号 `[文本]`
- [ ] **set to 的值使用圆括号** `set [v] to (值)` ✓
- [ ] **条件中的变量使用圆括号** `<(变量) > (90)>` ✓ （变量名不带方括号）
- [ ] 布尔条件使用尖括号 `<条件>`
- [ ] 下拉菜单有 `v` 后缀 `[选项 v]`
- [ ] 旋转使用 `cw/ccw`
- [ ] 时间单位用 `secs`
- [ ] C型积木有 `end` 结尾
- [ ] 嵌套代码使用**4个空格**缩进
- [ ] if-else 不使用 `else if`
- [ ] `if <条件> then` 在同一行
- [ ] `else` 单独一行
- [ ] `end` 单独一行
- [ ] JSON中使用 `\n` 换行
- [ ] JSON中正确转义引号 `\"`

---

## 17. 参考资源

- **官方Wiki文档**：https://en.scratch-wiki.info/wiki/Block_Plugin/Syntax
- **项目语法定义**：`d:\scratchblocks-main\syntax\commands.js`
- **官方测试用例**：`d:\scratchblocks-main\tests\all-blocks.txt`
- **在线验证工具**：https://scratchblocks.github.io/

---

**⚠️ 重要提醒**：

1. 生成任何Scratch代码前，**必须**先查阅本文档
2. 严格遵循官方语法，**不能自创格式**
3. **最常见的错误**：
   - `set [v] to [值]` ❌ → `set [v] to (值)` ✅
   - `<([分数 v]) > (90)>` ❌ → `<(分数) > (90)>` ✅ （变量名不带方括号）
4. 本文档基于官方Wiki和标准示例编写，如有更新以官方为准

---

*文档更新时间：2026-05-20*
*基于：https://en.scratch-wiki.info/wiki/Block_Plugin/Syntax*