JSON und JavaScript

In Blockly gibt es zwei Möglichkeiten, Blöcke zu definieren: JSON-Objekte, die Schlüssel/Wert-Paare verwenden, und JavaScript-Funktionen, die die Blockly-API aufrufen. Das JSON-Format wird bevorzugt, da es die Lokalisierung vereinfacht und leichter zu lesen und zu schreiben ist. Es kann jedoch nicht verwendet werden, um erweiterte Funktionen wie Mutatoren oder Validatoren direkt zu definieren. Sie müssen in JavaScript geschrieben werden, in der Regel als Erweiterungen.

Schlüsselbegriff :Die „JSON“-Objekte sind in Wirklichkeit einfache JavaScript-Objekte. Sie werden als JSON-Objekte bezeichnet, weil ihre Werte als JSON serialisiert werden müssen. Der Begriff wird verwendet, weil er (a) in der Blockly API vorkommt und (b) eine praktische Möglichkeit ist, zwischen den beiden verschiedenen Methoden zum Definieren von Blöcken zu unterscheiden.

JSON oder JavaScript verwenden

Dieser Block:

kann in JSON oder JavaScript so definiert werden.

JSON

Blockly.common.defineBlocksWithJsonArray([{
  "type": "string_length",
  "message0": 'length of %1',
  "args0": [
    {
      "type": "input_value",
      "name": "VALUE",
      "check": "String"
    }
  ],
  "output": "Number",
  "colour": 160,
  "tooltip": "Returns number of letters in the provided text.",
  "helpUrl": "http://www.w3schools.com/jsref/jsref_length_string.asp"
}]);

defineBlocksWithJsonArray konvertiert jedes JSON-Objekt in ein Blockdefinitionsobjekt mit einer init-Funktion. Die Objekte werden in Blockly.Blocks gespeichert.

JavaScript

Blockly.Blocks['string_length'] = {
  init: function() {
    this.appendValueInput('VALUE')
        .setCheck('String')
        .appendField('length of');
    this.setOutput(true, 'Number');
    this.setColour(160);
    this.setTooltip('Returns number of letters in the provided text.');
    this.setHelpUrl('http://www.w3schools.com/jsref/jsref_length_string.asp');
  }
};

Da Blockdefinitions-Objekte in Blockobjekte eingefügt werden, bezieht sich das Keyword this auf den tatsächlich erstellten Block.

Bei beiden Methoden wird ein Blockdefinitionsobjekt in Blockly.Blocks mit einem Schlüssel des Blocktypnamens (string_length) gespeichert. Das Blockdefinitionsobjekt hat eine einzelne Methode (init), die die Form des Blocks definiert.

JSON und JavaScript kombinieren

Das JSON-Format unterstützt in erster Linie die Definition des Erscheinungsbilds eines Blocks. Einige Funktionen wie Validatoren und Mutatoren, für die Sie eine Funktion definieren müssen, können nicht direkt definiert werden. Um dieses Problem zu beheben, sollten Sie so viel wie möglich von Ihrem Block mit JSON definieren und für den Rest JavaScript verwenden.

Im folgenden Beispiel wird eine Blockdefinition mit einer init-Funktion erstellt, die jsonInit verwendet, um ein JSON-Objekt zu laden, und die JavaScript API, um einen dynamischen Kurzinfo-Text zu definieren.

JavaScript

// Define the block structure in JSON.
var mathChangeJson = {
  "message0": "change %1 by %2",
  "args0": [
    {"type": "field_variable", "name": "VAR", "variable": "item", "variableTypes": [""]},
    {"type": "input_value", "name": "DELTA", "check": "Number"}
  ],
  "previousStatement": null,
  "nextStatement": null,
  "colour": 230
};

Blockly.Blocks['math_change'] = {
  init: function() {
    // Use jsonInit to load the JSON block structure.
    this.jsonInit(mathChangeJson);

    // Use JavaScript to define a tooltip function.
    // Assign 'this' to a variable for use in the tooltip closure below.
    var thisBlock = this;
    this.setTooltip(function() {
      return 'Add a number to variable "%1".'.replace('%1',
          thisBlock.getFieldValue('VAR'));
    });
  }
};

Block Definition API

In diesem Abschnitt werden die Objekte und Funktionen zusammengefasst, die zum Definieren benutzerdefinierter Blöcke verwendet werden.

Blockly.Blocks

Blockly.Blocks ist ein Objekt, in dem Blockdefinitionen gespeichert werden. Die Schlüssel sind Blocktypnamen und die Werte sind Blockdefinitionsobjekte. Verwenden Sie Blockly.Blocks, wenn Sie Blöcke mit JavaScript definieren:

Blockly.Blocks['my_block'] = {
  init: function() {/* ... */},
  onchange: function() {/* ... */},
  // ...
}

Ein häufiger Fehler ist, dass davon ausgegangen wird, dass Blockly.Blocks Blöcke speichert, und dann etwas wie das Folgende versucht wird. Dies schlägt fehl, da in Blockly.Blocks Blockdefinitionen und keine Blöcke gespeichert werden.

// Fails with "Blockly.Blocks.my_block.setColour is not a function".
Blockly.Blocks['my_block'].setColour(150);

defineBlocksWithJsonArray

defineBlocksWithJsonArray akzeptiert ein Array von JSON-Objekten, erstellt Blockdefinitionen daraus und fügt sie Blockly.Blocks hinzu.

Blockly.common.defineBlocksWithJsonArray([
  {
    type: 'my_block1',
    // ...
  }
  {
    type: 'my_block3',
    // ...
  }
  {
    type: 'my_block2',
    // ...
  }
]);

createBlockDefinitionsFromJsonArray und defineBlocks

createBlockDefinitionsFromJsonArray akzeptiert ein Array von JSON-Objekten und gibt ein Objekt zurück, das Blocktypennamen Blockdefinitionen zuordnet. Dieser Parameter wird in der Regel mit defineBlocks verwendet, wodurch die Blockdefinitionen zu Blockly.Blocks hinzugefügt werden.

const myBlockDefinitions = Blockly.common.createBlockDefinitionsFromJsonArray([
  {
    type: 'my_block1',
    // ...
  }
  {
    type: 'my_block3',
    // ...
  }
  {
    type: 'my_block2',
    // ...
  }
]);
Blockly.common.defineBlocks(myBlockDefinitions);

Block.jsonInit

jsonInit akzeptiert ein JSON-Objekt und ruft die entsprechenden Methoden für Block auf. Ein JSON-Objekt mit dem Schlüssel/Wert-Paar colour: 150 führt beispielsweise zu einem Aufruf von this.setColour(150). Verwenden Sie jsonInit in einer init-Funktion, um ein JSON-Objekt zu laden.

var myJson = {
  // ...
};

Blockly.Blocks['my_block'] = {
  init: function() {
    this.jsonInit(myJson);
    // The rest of the init function.
  }
};