注释

注释是贴在工作区上的一张便签，用来记下一段脚本是做什么的。Gandi 3.0 的注释能 写格式（标题、粗体、列表、引用），还能嵌入积木作为示范。

打开方式#

挂在积木上的那条用一根线连着它的积木，积木移到哪里它就跟到哪里。

写内容#

点进注释就可以开始写。顶上会展开一条工具条，鼠标移开又收起来，避免在一张小便签上常驻 一排按钮。

工具条从左到右：H1 H2 两级标题、B 加粗、I 斜体、<> 行内代码、☰ 列表、 ❝ 引用。再点一次变回普通文字。

不想动鼠标的话，几个 Markdown 记号输入完就地生效，记号本身消失：

列表和引用请用工具条上的 ☰ 和 ❝。 在行首输入 - 或 > 当场也会变成 列表和引用，但那一行存下来之后会退回普通文字，重开作品就没有了。工具条那 两个按钮做出来的是真的列表和引用，能够保存。

把积木嵌进去#

把工作区里的一段积木拖到注释上松手，注释里就多出一段积木。原来那段积木留在工作区 不动，注释里的是一份副本。

反过来，把注释里的那段积木拖到工作区，就得到一段真的积木。注释因此可以当作示范片段， 讲解和能直接取用的例子放在一起。

拖动时注释里已有的那一段会亮起来：落在它上面是替换，落在空白处是接在末尾。 每段积木右上角有个 ✕，用来删掉这一段。

拖动、缩放、折叠#

• 拖：抓注释顶上那条横杠。
• 缩放：拖右下角那个小三角向外放大。嵌入一段积木时注释会自动增高。
• 折叠：点左上角的 ▾。折起来只剩一条，上面是首行文字加一句「⟨N 段积木⟩」。 再点一次展开。

细节#

• 注释存的是纯 Markdown 原文，不是 HTML。拖进去的积木会经当前作品的积木定义打印成 ```gandi-dsl 围栏，例如 when.flagclicked(() => { looks.say("Hello"); });。 Agent 也能把这样的围栏写进积木页 DSL 的注释文字里；它是 Gandi 积木 DSL，不是会执行的 JavaScript。 预览使用注释所属工作区的变量、自制积木和已安装扩展，不会为了预览安装扩展。 包含变量声明、多段脚本、代码框、注释或超过 600 块积木的示例显示完整 DSL 原文，不只显示第一段或截断缩略图。 拖出来时按指针落点工作区的角色和缩放再编译；单击、区外松手、只读工作区、积木栏或取消拖动都不会插入。 编译失败会报错，不会猜测积木。
• 这不只是形式问题：存成 HTML 就要用 innerHTML 渲染，而作品是互相传递的，只要有人 在 project.json 里把注释改成一段脚本，打开时就会执行。纯 Markdown 里没有任何位置 能放 HTML 标签。
• 旧格式不兼容拖放：过去的 ```blocks XML 围栏会作为普通文本展示，不再被识别为 可拖出的积木。旧 gandi-rich 记录的非 XML 正文仍会安全迁移成 Markdown，旧 XML 示例不再导入。 打开旧作品前应先备份，若依赖旧示例请手动改写成 gandi-dsl。
• 注释里按 Delete 删的是文字，不会删积木，编辑区把按键拦了下来。
• 注释的正文进全局搜索的索引，结果列表上有「注释」一档筛选，点一条 即跳到那条注释；查找替换也能改注释里的文字。

相关#

• 自制积木 —— 给自制积木的定义块挂一条注释，说明它怎么用。
• 积木栏 —— 注释里的积木片段拖出来就是真积木，和从积木栏拖一块一样。