title: 创建自定义块 - 样式指南
Custom Blocks: Style Guide
原文链接：https://developers.google.com/blockly/guides/create-custom-blocks/style-guide
多年来，Blockly和Blockly Games团队学到了许多适用于开发新块的课程。以下是我们所犯错误的集合，或者他人通常犯的错误。
些是我们使用Blockly的视觉风格学到的一般教训，可能不适用于所有用例或设计。存在其他解决方案。这也不是用户可能遇到的问题和如何避免他们的问题的详尽列表。每个案例都有点不同，并有自己的权衡。
1. 条件与循环
新用户最困难的块是条件和循环。许多基于块的环境将这两个块组合成相同的“控件”类别，两个块具有相同的形状和相同的颜色。这通常导致沮丧，因为新用户混淆两个块。阻止推荐将条件和循环移动到单独的“逻辑”和“循环”类别，每个类别具有不同的颜色。这清楚地表明，这些是不同的想法，行为不同，尽管具有类似的形状。
建议：保持条件和循环分离。
2. 一个列表
新手程序员在第一次遇到基于零的列表时反应不当。因此，Blockly通过使列表和字符串索引基于一个，跟随Lua和Lambda Moo的指导。
对于Blockly的更高级使用，支持从零开始的列表，以便更容易转换到文本。对于年轻或更多的新手观众，仍然建议基于单一的索引。
建议：1是第一个数字。
3. 用户输入
有三种方法从用户获取参数。下拉是最严格的，适合简单的教程和练习。输入字段允许更多的自由，并且有利于更多的创造性活动。值块输入（通常带有阴影块）提供了计算值（例如，随机生成器）而不仅仅是静态值的机会。
建议：选择适合您用户的输入方法。
4.实时图像块
块的文档应包括它所引用的块的图像。拍摄截图很容易。但是如果有50个这样的图像，并且应用被翻译成50种语言，突然一个人维护2,500个静态图像。然后颜色方案改变，并且2,500个图像需要再次更新 -。
为了从这个维护噩梦中解脱出来，Blockly Games用只读模式下的Blockly实例替换了所有的屏幕截图。结果看起来与图片相同，但保证是最新的。只读模式使国际化成为可能。
建议：如果您支持多种语言，请使用只读模式。
5. 表达左的另一种方法
美国儿童的反馈（虽然有趣的是不是来自其他国家）显示左右之间的混乱。这通过添加箭头来解决。如果方向是相对的（例如，对于化身），箭头的风格是重要的。当化身朝向相反方向时，A→直箭头或↱箭头混乱。最有帮助的是圆形箭头，即使在转动的角度小于箭头指示的情况下。
建议：如果可能，补充文本与Unicode图标。
6. 高级块
在可能的情况下，应该采用更高级别的方法，即使它降低了执行性能或灵活性。考虑使用此Apps脚本表达式：
SpreadsheetApp.getActiveSheet().getDataRange().getValues()
在保留所有潜在能力的1：1映射下，上述表达式将使用四个块来构建。但Blockly的目标是更高级的，并提供一个封装整个表达式的块。目标是优化95％的情况，即使它使剩余的5％更困难。 Blockly不打算替代基于文本的语言，它旨在帮助用户覆盖初始学习曲线，以便他们可以使用基于文本的语言。
建议：不要盲目地将整个API转换为块。
7.可选的返回值
许多基于文本编程的函数执行一个操作，然后返回一个值。可以使用或不使用此返回值。一个例子是栈的pop（）函数。可以调用Pop来获取和删除最后一个元素，也可以调用它来删除返回值被忽略的最后一个元素。
var last = stack.pop(); // Get and remove last element.
stack.pop(); // Just remove last element.
基于块的语言通常不利于忽略返回值。值块必须插入接受值的东西。有几个策略来处理这个问题。
- a）解决问题。大多数基于块的语言设计语言以避免这些情况。例如，Scratch没有任何具有副作用和返回值的块。
- b）提供两个块。如果工具箱中的空间不是问题，一个简单的解决方案是提供每种类型的块中的两个，一个具有和一个没有返回值。缺点是，这可能导致一个令人困惑的工具箱与许多几乎相同的块。
- c）变换一个块。使用下拉列表，复选框或其他控件，允许用户选择是否有返回值。然后，块根据其选项更改形状。在Blockly的列表访问块中可以看到一个例子。
d）去掉值（eat the value）。第一个版本的App Inventor创建了一个特殊的管道块，可以管理任何连接的值。用户不了解此概念，第二版的App Inventor删除了管道块，建议用户将该值分配给一次性变量。
建议：每个策略都有利弊，选择适合您的用户。
8. Growing blocks
某些块可能需要可变数量的输入。示例是将任意数字集合相加的添加块，或者具有任意组的elseif子句的if / elseif / else块，或者具有任意数量的初始化元素的列表构造器。有几种策略，每种策略都有其优点和缺点。
- a）最简单的方法是使用户从较小的块中组成块。一个示例是通过嵌套两个两个数字加法块来添加三个数字。另一个例子是只提供if / else块，并让用户嵌套他们创建elseif条件。
这种方法的优点是其最初的简单性（对于用户和开发者）。缺点是在存在大量嵌套的情况下，代码变得非常麻烦并且对于用户来说难以阅读和维护。
- b）另一种方法是动态扩展块，以便在末端总有一个空闲输入。同样，如果在末尾有两个空闲输入，块将删除最后一个输入。这是App Inventor的第一个版本使用的方法
App Inventor的用户对于自动增长的块不喜欢几个原因。首先，总是有一个自由的输入，程序从来没有“完整”。第二，在堆栈中间插入一个元素是令人沮丧的，因为它涉及断开编辑下面的所有元素并重新连接它们。也就是说，如果顺序不重要，并且用户可以在他们的程序中感到空洞，这是一个非常方便的选择。
- c）为了解决孔问题，一些开发人员添加+/-按钮到手动添加或删除输入的块。打开Roberta使用两个这样的按钮从底部添加或删除输入。其他开发者在每行添加两个按钮，使得可以适应从堆栈的中间插入和删除。其他在每行添加两个向上/向下按钮，以便可以适应堆栈的重新排序。
这个策略是一系列选项，从每个块只有两个按钮，到每行四个按钮。一方面，用户无法执行他们所需的操作的危险，另一方面，用户界面中充满了按钮，它看起来像是企业号（he starship Enterprise.）。
- d）最灵活的方法是在块中添加一个mutator bubble。这表示为打开该块的配置对话框的单个按钮。元素可以随意添加，删除或重新排列。
这种方法的缺点是它的mutator对新手用户不直观。引入突变者需要某种形式的指令。面向年幼儿童的基于块的应用程序不应使用mutator。虽然一旦学到，他们对于高级用户是无价的。
建议：每个策略都有利弊，选择适合您的用户。
9.整洁的代码的生成
高级Blockly用户应该能够查看生成的代码（JavaScript，Python，PHP，Lua，Dart等）并立即识别他们编写的程序。这意味着需要额外的努力来保持这个机器生成的代码可读。多余的括号，数字变量，粉碎的空格和冗长的代码模板都会妨碍生成优雅的代码。生成的代码应包含注释，并且应符合Google的样式指南Google's style guides。
建议：为您生成的代码感到自豪。显示给用户。
10.语言依赖
对整洁的代码的期望的副作用是Blockly的行为在很大程度上根据交叉编译语言的行为来定义。最常见的输出语言是JavaScript，但是如果Blockly被交叉编译为不同的语言，则不应进行不合理的尝试以保留两种语言的确切行为。例如，在JavaScript中，空字符串为false，而在Lua中为true。定义一个单独的行为模式，Blockly的代码执行，而不管目标语言如何，将导致看起来像从GWT编译器出来的不可维护的代码。
建议：块式不是一种语言，允许现有语言影响行为。