CodingPirates/blockly
1
0
Fork 0
mirror of https://github.com/google/blockly.git synced 2026-05-02 01:50:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): ARIA roles and labels for built-in fields (#9788)

Browse Source 
* chore(docs): add information about ARIA for built-in fields

* chore: tweak dropdown wording

* chore: add accessibility information to Anatomy of a Field

* chore(format): line length

* chore: update section on focusability

* chore: fix phrasing
This commit is contained in:
Rachel Fenichel
2026-05-01 20:02:15 +01:00
committed by GitHub
parent 4fe25d9071
commit f5c65a5bbf
9 changed files with 134 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/docs/docs/guides/create-custom-blocks/fields/anatomy-of-a-field.mdx
+38 -4
View File
@@ -27,7 +27,8 @@ and may optionally be part of the [on-block display](#on-block-display).
In general, editable fields allow the user to make changes to the code, while
non-editable fields display information to the user about the block.
Editable fields may show a rich editor when clicked.
Editable fields may show a rich editor when clicked or activated with the
keyboard.
Editable fields include:
@@ -43,6 +44,25 @@ Non-editable fields include:
- [Label Serializable](/guides/create-custom-blocks/fields/built-in-fields/label-serializable)
- [Image](/guides/create-custom-blocks/fields/built-in-fields/image)
## Focusable vs non-focusable fields
Focusable fields can be navigated to and acted on with the keyboard. A field is
focusable if it is visible and clickable or currently editable. Some
non-editable fields are focusable, such as images with click handlers. If a
field is focusable it must specify a single focusable element to be visited when
traversing blocks. Blockly ensures that the focusable element is in the
accessibility tree in an appropriate location.
Non-focusable fields such as labels cannot be navigated to with the keyboard.
## ARIA label
All fields have an ARIA label, which is a string containing human-readable
information about the field's type and value. Blockly exposes the ARIA label to
screen readers by attaching it to the field's focusable element or including it
in the parent block's ARIA label. All built-in fields compute their ARIA labels
automatically.
## Serialization
A serializable field's value gets encoded in the save format (JSON or XML). All
@@ -93,6 +113,19 @@ complexity.
| Angle | Contains a background rect, text element, and a degree symbol. |
| Turtle | Contains a background rect, text element, and many SVG elements used to construct the turtle graphic. |
Focusable fields must designate a focusable DOM element with a unique ID for
their on-block display. Blockly places this element in the accessibility tree
and moves focus to it through keyboard navigation. When the field is focused its
focusable DOM element will have the `blocklyActiveFocus` or
`blocklyPassiveFocus` CSS class added. Blockly's built-in fields show focus
with a yellow outline.
The focusable element must have the correct ARIA role. Most focusable fields
have an ARIA role of `button` to indicate that they can be clicked or activated
with the keyboard. An exception is the checkbox field, which has an ARIA role
of `checkbox`. Non-focusable fields should be removed from the accessibility
tree by applying `aria-hidden` to the root of the field.
## Editor display
When a user clicks on an editable field, the field may display an
@@ -107,6 +140,10 @@ complexity.
| Number input | Text editor overlaid above the on-block display. Users can type; the editor may change color to indicate bad values. |
| Angle picker | The angle picker has both a text editor for typing numbers and a draggable editor for selecting angles visually. |
Blockly automatically moves focus into the field editor when activated. The
developer is responsible for the accessibility of their field editor, including
setting appropriate [ARIA role and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques).
## Other display modes
Collapsed mode: the user collapses the block.The block displays a text representation
@@ -115,7 +152,4 @@ fields.
![Turtle field block collapsing](/images/fields/yertle_collapsing.gif)
Accessibility mode: users may be using a screenreader or similar technology to
interact with Blockly. The text of the field may be read out to the user.
[field-generator]: /guides/create-custom-blocks/code-generation/block-code#get-field-values
packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/checkbox.mdx
+8 -1
View File
@@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem';
# Checkbox fields
A checkbox field stores a string as its value, and a string as its text. Its
A checkbox field stores a string as its value and a string as its text. Its
value is either `'TRUE'` or `'FALSE'`, and its text is either `'true'` or
`'false'`.
@@ -99,6 +99,13 @@ The checkbox constructor takes in an optional value and an optional
when diffing workspaces.
</TabItem>
</Tabs>
## Accessibility
A checkbox field's on-block display has the ARIA role `checkbox`. There is
no editor: the on-block display simply toggles when clicked. Its ARIA value
is either `'checked'` or `'unchecked'`. The ARIA label is `checkbox: <ARIA value>`.
## Customization
### Checkmark character
packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/dropdown.mdx
+25 -4
View File
@@ -34,10 +34,12 @@ collapsed.](/images/fields/dropdown/collapsed.png)
The dropdown constructor takes in a menu generator and an optional
[validator](#creating-a-dropdown-validator). The menu generator is either an
array of options (where each option contains a human-readable part and a
language-neutral string) or a function that generates an array of options. The
human-readable part of each option can be a string, an image, or an HTML element
and the array can contain a mixture of options of different types.
array of options or a function that generates an array of options. A dropdown
can contain a mixture of options of different types. Each option
contains:
- A human-readable part which may be a string, image, or HTML element
- A language-neutral string
- An optional ARIA label
### Simple text dropdowns
@@ -402,6 +404,25 @@ text should be a valid language-neutral option key.
</TabItem>
</Tabs>
## Accessibility
A dropdown field's ARIA label is `dropdown: <ARIA value>`.
The ARIA value is computed based on the type of the selected option.
- Simple text dropdowns use the human-readable string directly.
- Image dropdowns use the `ariaLabel` of the selected image or fall back to the
alt text for the selected image.
- HTML dropdowns use the computed `aria-label` of the `HTMLElement`. You are
responsible for making sure that your element either uses appropriate
[semantic HTML](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Accessibility/HTML)
or sets its [ARIA role and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques) appropriately.
- Providing an ARIA value in the option definition overrides the automatic
label computation.
A dropdown field’s on-block display has the ARIA role `button`. Activating the
field opens a dropdown menu with the role `listbox`. If you use an HTML dropdown
you are responsible for ensuring that the contents are accessible.
## Customization
### Dropdown arrow
packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/image.mdx
+14 -3
View File
@@ -9,9 +9,10 @@ import TabItem from '@theme/TabItem';
# Image fields
An image field stores a string as its value, and a string as its text. Its
An image field stores a string as its value and a string as its text. Its
value is the src of the image, while its text is an alt string
describing/representing the image.
describing/representing the image. The alt text is also displayed when the
parent block is collapsed.
#### Image field
@@ -67,7 +68,7 @@ The image constructor takes in:
| `src` | A string that points to a [raster image](https://developer.mozilla.org/en-US/docs/Glossary/raster_image) file. |
| `width` | Must cast to a non-zero number. |
| `height` | Must cast to a non-zero number. |
| `opt_alt` | (Optional) A string that accurately describes/represents the image. This is used instead of the image when the block is collapsed. If it is `null` or `undefined` an empty string will be used. |
| `opt_alt` | (Optional) A string that accurately describes/represents the image. If it is `null` or `undefined` an empty string will be used. |
| `opt_onClick` | (Optional) A function to call when the field is clicked. |
| `opt_flipRtl` | (Optional) A boolean. If `true`, the image is flipped across the vertical axis when in right-to-left mode. Defaults to `false`. Useful for "turn left" and "turn right" icons. |
@@ -75,6 +76,16 @@ The image constructor takes in:
Image fields are not serializable.
## Accessibility
An image field's ARIA label is `image: <alt text>`. The alt text is also
displayed when the parent block is collapsed.
Clickable images have an ARIA role of `button`. Image fields that do not have
click handlers have an ARIA role of `none`.
Follow [AFB guidelines](https://afb.org/digital-inclusion/accessibility-resources/writing-effective-image-descriptions)
for writing good alt text. Return `null` or `undefined` to indicate a purely decorative image.
## Click handler
:::note
packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label-serializable.mdx
+8
View File
@@ -86,6 +86,14 @@ class string. Both default to an empty string.
label field, and the node's inner text is the value to apply to the field.
</TabItem>
</Tabs>
## Accessibility
Serializable label fields cannot be focused directly with keyboard navigation.
The on-block display has the ARIA role `generic`. There is no editor display.
The label's text is used to construct the parent block's ARIA label.
## Validators
Serializable label fields do not support validators, because they are not
packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label.mdx
+6
View File
@@ -89,6 +89,12 @@ If you would like your label to be serialized, because it is being changed
programmatically, see the [Serializable Label](/guides/create-custom-blocks/fields/built-in-fields/label-serializable)
field.
## Accessibility
Label fields cannot be focused directly with keyboard navigation. The on-block
display has the ARIA role `generic`. There is no editor display. The label's
text is used to construct the parent block's ARIA label.
## Validators
Label fields do not support validators, because they are not editable.
packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/number.mdx
+20 -3
View File
@@ -102,6 +102,25 @@ The `value` should cast to a number. If it does not 0 will be used.
inner text value follows the same rules as the constructor value.
</TabItem>
</Tabs>
## 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/number#accessibility)
“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
@@ -127,9 +146,7 @@ used to make the field only accept multiples of .01, 10, 42, etc.
### Positive numbers
To force your field to only accept positive numbers, set the `min` value to
1.
To force your field to only accept positive numbers, set the `min` value to 1.
### Integers
packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/text-input.mdx
+7
View File
@@ -97,6 +97,13 @@ The JSON definition also allows you to set the [spellcheck](#spellcheck) option.
text value follows the same rules as the constructor value.
</TabItem>
</Tabs>
## Accessibility
A text input field's ARIA label is `text: <ARIA value>`. The on-block display
has the ARIA role `button`. Activating the field overlays and focuses an HTML
text input.
## Customization
### Spellcheck
packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/variable.mdx
+8
View File
@@ -169,6 +169,14 @@ types, and an optional default type.
follows the same rules as the constructor's variable name parameter.
</TabItem>
</Tabs>
## Accessibility
A variable field's ARIA label is `variable: '<ARIA value>'`, where the ARIA
value is the name of the variable. A variable field's on-block display has the
ARIA role `button`. Activating the field opens a dropdown menu with the role
`listbox`.
## Creating a variable validator
:::note