Number fields

A number field stores a number as its value, and a string as its text. Its value is always a valid number as defined by the constraints given to the field at creation; its text could be any string entered into its editor.

Number field

Number field with editor open

Number field on collapsed block

Creation

JSON

{
  "type": "example_number",
  "message0": "number: %1",
  "args0": [
    {
      "type": "field_number",
      "name": "FIELDNAME",
      "value": 100,
      "min": 0,
      "max": 100,
      "precision": 10
    }
  ]
}

JavaScript

Blockly.Blocks['example_number'] = {
  init: function() {
    this.appendDummyInput()
        .appendField("number:")
        .appendField(new Blockly.FieldNumber(100, 0, 100, 10), 'FIELDNAME');
  }
};

The number constructor takes in the following:

• an optional value
• an optional min
• an optional max
• an optional precision
• an optional validator

The value should cast to a number. If it does not 0 will be used.

Serialization

JSON

The JSON for a number field looks like so:

{
  "fields": {
    "FIELDNAME": 0
  }
}

Where FIELDNAME is a string referencing a number field, and the value is the value to apply to the field. The value follows the same rules as the constructor value.

XML

The XML for a number field looks like so:

<field name="FIELDNAME">0</field>

The field node's name attribute contains a string referencing a number field, and the node's inner text is the value to apply to the field. The inner text value follows the same rules as the constructor value.

Accessibility

A number field's ARIA label is number: <ARIA value>. A number fields's on-block display has the ARIA role button. Activating the field overlays and focuses an HTML text input.

note

The HTML input type is text rather than number because the semantics of an HTML number input do not match Blockly's behaviour. Blockly number fields provide feedback for invalid values and handle the value Infinity. According to MDN “the implicit role for the <input type="number"> element is spinbutton. [...] With <input type="number">, there is a risk of users accidentally incrementing a number when they're trying to do something else. Additionally, if users try to enter something that's not a number, there's no explicit feedback about what they're doing wrong.”

Constraints

Constraints can be set in the field definition, or by using the setConstraints function.

Minimum value

The min value sets the smallest/most-negative value the field is allowed to contain.

Maximum value

The max value sets the largest/most-positive value the field is allowed to contain.

Rounding

The precision rounds the value to the nearest multiple of precision. This can be used to make the field only accept multiples of .01, 10, 42, etc.

Common constraints

Positive numbers

To force your field to only accept positive numbers, set the min value to 1.

Integers

To force your field to only accept integers, set the precision to 1.

Creating a number validator

note

For information on validators in general see Validators.

A number field's value is a number, so any validators must accept a number and return a number, null, or undefined.

Here is an example of a validator that changes the value to be either 0 or 1 depending on if the value was odd or even.

function(newValue) {
  return newValue % 2;
}