@wordpress/block-editor
Version:
727 lines (415 loc) • 23.9 kB
Markdown
# Block Editor
This module allows you to create and use standalone block editors.
## Installation
Install the module
```bash
npm install @wordpress/block-editor --save
```
_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as IE browsers then using [core-js](https://github.com/zloirock/core-js) will add polyfills for these methods._
## Usage
```js
import {
BlockEditorProvider,
BlockList,
WritingFlow,
ObserveTyping,
} from '@wordpress/block-editor';
import { SlotFillProvider, Popover } from '@wordpress/components';
import { useState } from '@wordpress/element';
function MyEditorComponent() {
const [ blocks, updateBlocks ] = useState( [] );
return (
<BlockEditorProvider
value={ blocks }
onInput={ ( blocks ) => updateBlocks( blocks ) }
onChange={ ( blocks ) => updateBlocks( blocks ) }
>
<SlotFillProvider>
<Popover.Slot name="block-toolbar" />
<WritingFlow>
<ObserveTyping>
<BlockList />
</ObserveTyping>
</WritingFlow>
<Popover.Slot />
</SlotFillProvider>
</BlockEditorProvider>
);
}
// Make sure to load the block editor stylesheets too
// import '@wordpress/components/build-style/style.css';
// import '@wordpress/block-editor/build-style/style.css';
```
In this example, we're instantiating a block editor. A block editor is composed by a `BlockEditorProvider` wrapper component where you pass the current array of blocks and on each change the `onInput` or `onChange` callbacks are called depending on whether the change is considered persistent or not.
Inside `BlockEditorProvider`, you can nest any of the available `@wordpress/block-editor` UI components to build the UI of your editor.
In the example above we're rendering the `BlockList` to show and edit the block list. For instance we could add a custom sidebar and use the `BlockInspector` component to be able to edit the advanced settings for the currently selected block. (See the [API](#API) for the list of all the available components).
The `Popover.Slot` with the `name="block-toolbar"` prop is used to render the toolbar for a selected block.
In the example above, there's no registered block type, in order to use the block editor successfully make sure to register some block types. For instance, registering the core block types can be done like so:
```js
import { registerCoreBlocks } from '@wordpress/block-library';
registerCoreBlocks();
// Make sure to load the block stylesheets too
// import '@wordpress/block-library/build-style/style.css';
// import '@wordpress/block-library/build-style/editor.css';
// import '@wordpress/block-library/build-style/theme.css';
```
## API
<!-- START TOKEN(Autogenerated API docs) -->
<a name="AlignmentControl" href="#AlignmentControl">#</a> **AlignmentControl**
Undocumented declaration.
<a name="AlignmentToolbar" href="#AlignmentToolbar">#</a> **AlignmentToolbar**
Undocumented declaration.
<a name="Autocomplete" href="#Autocomplete">#</a> **Autocomplete**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/autocomplete/README.md>
<a name="BlockAlignmentControl" href="#BlockAlignmentControl">#</a> **BlockAlignmentControl**
Undocumented declaration.
<a name="BlockAlignmentToolbar" href="#BlockAlignmentToolbar">#</a> **BlockAlignmentToolbar**
Undocumented declaration.
<a name="BlockBreadcrumb" href="#BlockBreadcrumb">#</a> **BlockBreadcrumb**
Block breadcrumb component, displaying the hierarchy of the current block selection as a breadcrumb.
_Returns_
- `WPElement`: Block Breadcrumb.
<a name="BlockColorsStyleSelector" href="#BlockColorsStyleSelector">#</a> **BlockColorsStyleSelector**
Undocumented declaration.
<a name="BlockContextProvider" href="#BlockContextProvider">#</a> **BlockContextProvider**
Component which merges passed value with current consumed block context.
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-context/README.md>
_Parameters_
- _props_ `BlockContextProviderProps`:
<a name="BlockControls" href="#BlockControls">#</a> **BlockControls**
Undocumented declaration.
<a name="BlockEdit" href="#BlockEdit">#</a> **BlockEdit**
Undocumented declaration.
<a name="BlockEditorKeyboardShortcuts" href="#BlockEditorKeyboardShortcuts">#</a> **BlockEditorKeyboardShortcuts**
Undocumented declaration.
<a name="BlockEditorProvider" href="#BlockEditorProvider">#</a> **BlockEditorProvider**
Undocumented declaration.
<a name="BlockFormatControls" href="#BlockFormatControls">#</a> **BlockFormatControls**
Undocumented declaration.
<a name="BlockIcon" href="#BlockIcon">#</a> **BlockIcon**
Undocumented declaration.
<a name="BlockInspector" href="#BlockInspector">#</a> **BlockInspector**
Undocumented declaration.
<a name="BlockList" href="#BlockList">#</a> **BlockList**
Undocumented declaration.
<a name="BlockMover" href="#BlockMover">#</a> **BlockMover**
Undocumented declaration.
<a name="BlockNavigationDropdown" href="#BlockNavigationDropdown">#</a> **BlockNavigationDropdown**
Undocumented declaration.
<a name="BlockPreview" href="#BlockPreview">#</a> **BlockPreview**
BlockPreview renders a preview of a block or array of blocks.
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-preview/README.md>
_Parameters_
- _preview_ `Object`: options for how the preview should be shown
- _preview.blocks_ `Array|Object`: A block instance (object) or an array of blocks to be previewed.
- _preview.viewportWidth_ `number`: Width of the preview container in pixels. Controls at what size the blocks will be rendered inside the preview. Default: 700.
_Returns_
- `WPComponent`: The component to be rendered.
<a name="BlockSelectionClearer" href="#BlockSelectionClearer">#</a> **BlockSelectionClearer**
Undocumented declaration.
<a name="BlockSettingsMenu" href="#BlockSettingsMenu">#</a> **BlockSettingsMenu**
Undocumented declaration.
<a name="BlockSettingsMenuControls" href="#BlockSettingsMenuControls">#</a> **BlockSettingsMenuControls**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-settings-menu-controls/README.md>
_Parameters_
- _props_ `Object`: Fill props.
_Returns_
- `WPElement`: Element.
<a name="BlockTitle" href="#BlockTitle">#</a> **BlockTitle**
Renders the block's configured title as a string, or empty if the title
cannot be determined.
_Usage_
```jsx
<BlockTitle clientId="afd1cb17-2c08-4e7a-91be-007ba7ddc3a1" />
```
_Parameters_
- _props_ `Object`:
- _props.clientId_ `string`: Client ID of block.
_Returns_
- `?string`: Block title.
<a name="BlockToolbar" href="#BlockToolbar">#</a> **BlockToolbar**
Undocumented declaration.
<a name="BlockVerticalAlignmentControl" href="#BlockVerticalAlignmentControl">#</a> **BlockVerticalAlignmentControl**
Undocumented declaration.
<a name="BlockVerticalAlignmentToolbar" href="#BlockVerticalAlignmentToolbar">#</a> **BlockVerticalAlignmentToolbar**
Undocumented declaration.
<a name="ButtonBlockerAppender" href="#ButtonBlockerAppender">#</a> **ButtonBlockerAppender**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/button-block-appender/README.md>
<a name="ColorPalette" href="#ColorPalette">#</a> **ColorPalette**
Undocumented declaration.
<a name="ColorPaletteControl" href="#ColorPaletteControl">#</a> **ColorPaletteControl**
Undocumented declaration.
<a name="ContrastChecker" href="#ContrastChecker">#</a> **ContrastChecker**
Undocumented declaration.
<a name="CopyHandler" href="#CopyHandler">#</a> **CopyHandler**
Undocumented declaration.
<a name="createCustomColorsHOC" href="#createCustomColorsHOC">#</a> **createCustomColorsHOC**
A higher-order component factory for creating a 'withCustomColors' HOC, which handles color logic
for class generation color value, retrieval and color attribute setting.
Use this higher-order component to work with a custom set of colors.
_Usage_
```jsx
const CUSTOM_COLORS = [ { name: 'Red', slug: 'red', color: '#ff0000' }, { name: 'Blue', slug: 'blue', color: '#0000ff' } ];
const withCustomColors = createCustomColorsHOC( CUSTOM_COLORS );
// ...
export default compose(
withCustomColors( 'backgroundColor', 'borderColor' ),
MyColorfulComponent,
);
```
_Parameters_
- _colorsArray_ `Array`: The array of color objects (name, slug, color, etc... ).
_Returns_
- `Function`: Higher-order component.
<a name="DefaultBlockAppender" href="#DefaultBlockAppender">#</a> **DefaultBlockAppender**
Undocumented declaration.
<a name="FontSizePicker" href="#FontSizePicker">#</a> **FontSizePicker**
Undocumented declaration.
<a name="getColorClassName" href="#getColorClassName">#</a> **getColorClassName**
Returns a class based on the context a color is being used and its slug.
_Parameters_
- _colorContextName_ `string`: Context/place where color is being used e.g: background, text etc...
- _colorSlug_ `string`: Slug of the color.
_Returns_
- `?string`: String with the class corresponding to the color in the provided context. Returns undefined if either colorContextName or colorSlug are not provided.
<a name="getColorObjectByAttributeValues" href="#getColorObjectByAttributeValues">#</a> **getColorObjectByAttributeValues**
Provided an array of color objects as set by the theme or by the editor defaults,
and the values of the defined color or custom color returns a color object describing the color.
_Parameters_
- _colors_ `Array`: Array of color objects as set by the theme or by the editor defaults.
- _definedColor_ `?string`: A string containing the color slug.
- _customColor_ `?string`: A string containing the customColor value.
_Returns_
- `?Object`: If definedColor is passed and the name is found in colors, the color object exactly as set by the theme or editor defaults is returned. Otherwise, an object that just sets the color is defined.
<a name="getColorObjectByColorValue" href="#getColorObjectByColorValue">#</a> **getColorObjectByColorValue**
Provided an array of color objects as set by the theme or by the editor defaults, and a color value returns the color object matching that value or undefined.
_Parameters_
- _colors_ `Array`: Array of color objects as set by the theme or by the editor defaults.
- _colorValue_ `?string`: A string containing the color value.
_Returns_
- `?Object`: Color object included in the colors array whose color property equals colorValue. Returns undefined if no color object matches this requirement.
<a name="getFontSize" href="#getFontSize">#</a> **getFontSize**
Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values.
If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned.
_Parameters_
- _fontSizes_ `Array`: Array of font size objects containing at least the "name" and "size" values as properties.
- _fontSizeAttribute_ `?string`: Content of the font size attribute (slug).
- _customFontSizeAttribute_ `?number`: Contents of the custom font size attribute (value).
_Returns_
- `?Object`: If fontSizeAttribute is set and an equal slug is found in fontSizes it returns the font size object for that slug. Otherwise, an object with just the size value based on customFontSize is returned.
<a name="getFontSizeClass" href="#getFontSizeClass">#</a> **getFontSizeClass**
Returns a class based on fontSizeName.
_Parameters_
- _fontSizeSlug_ `string`: Slug of the fontSize.
_Returns_
- `string`: String with the class corresponding to the fontSize passed. The class is generated by appending 'has-' followed by fontSizeSlug in kebabCase and ending with '-font-size'.
<a name="getFontSizeObjectByValue" href="#getFontSizeObjectByValue">#</a> **getFontSizeObjectByValue**
Returns the corresponding font size object for a given value.
_Parameters_
- _fontSizes_ `Array`: Array of font size objects.
- _value_ `number`: Font size value.
_Returns_
- `Object`: Font size object.
<a name="getGradientSlugByValue" href="#getGradientSlugByValue">#</a> **getGradientSlugByValue**
Retrieves the gradient slug per slug.
_Parameters_
- _gradients_ `Array`: Gradient Palette
- _value_ `string`: Gradient value
_Returns_
- `string`: Gradient slug.
<a name="getGradientValueBySlug" href="#getGradientValueBySlug">#</a> **getGradientValueBySlug**
Retrieves the gradient value per slug.
_Parameters_
- _gradients_ `Array`: Gradient Palette
- _slug_ `string`: Gradient slug
_Returns_
- `string`: Gradient value.
<a name="InnerBlocks" href="#InnerBlocks">#</a> **InnerBlocks**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md>
<a name="Inserter" href="#Inserter">#</a> **Inserter**
Undocumented declaration.
<a name="InspectorAdvancedControls" href="#InspectorAdvancedControls">#</a> **InspectorAdvancedControls**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-advanced-controls/README.md>
<a name="InspectorControls" href="#InspectorControls">#</a> **InspectorControls**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md>
<a name="JustifyContentControl" href="#JustifyContentControl">#</a> **JustifyContentControl**
Undocumented declaration.
<a name="JustifyToolbar" href="#JustifyToolbar">#</a> **JustifyToolbar**
Undocumented declaration.
<a name="LineHeightControl" href="#LineHeightControl">#</a> **LineHeightControl**
Undocumented declaration.
<a name="MediaPlaceholder" href="#MediaPlaceholder">#</a> **MediaPlaceholder**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-placeholder/README.md>
<a name="MediaReplaceFlow" href="#MediaReplaceFlow">#</a> **MediaReplaceFlow**
Undocumented declaration.
<a name="MediaUpload" href="#MediaUpload">#</a> **MediaUpload**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-upload/README.md>
<a name="MediaUploadCheck" href="#MediaUploadCheck">#</a> **MediaUploadCheck**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-upload/README.md>
<a name="MultiSelectScrollIntoView" href="#MultiSelectScrollIntoView">#</a> **MultiSelectScrollIntoView**
> **Deprecated**
Scrolls the multi block selection end into view if not in view already. This
is important to do after selection by keyboard.
<a name="NavigableToolbar" href="#NavigableToolbar">#</a> **NavigableToolbar**
Undocumented declaration.
<a name="ObserveTyping" href="#ObserveTyping">#</a> **ObserveTyping**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/observe-typing/README.md>
<a name="PanelColorSettings" href="#PanelColorSettings">#</a> **PanelColorSettings**
Undocumented declaration.
<a name="PlainText" href="#PlainText">#</a> **PlainText**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/plain-text/README.md>
<a name="PreserveScrollInReorder" href="#PreserveScrollInReorder">#</a> **PreserveScrollInReorder**
Undocumented declaration.
<a name="RichText" href="#RichText">#</a> **RichText**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md>
<a name="RichTextShortcut" href="#RichTextShortcut">#</a> **RichTextShortcut**
Undocumented declaration.
<a name="RichTextToolbarButton" href="#RichTextToolbarButton">#</a> **RichTextToolbarButton**
Undocumented declaration.
<a name="SETTINGS_DEFAULTS" href="#SETTINGS_DEFAULTS">#</a> **SETTINGS_DEFAULTS**
The default editor settings
_Type Definition_
- _SETTINGS_DEFAULT_ `Object`
_Properties_
- _alignWide_ `boolean`: Enable/Disable Wide/Full Alignments
- _supportsLayout_ `boolean`: Enable/disable layouts support in container blocks.
- _imageEditing_ `boolean`: Image Editing settings set to false to disable.
- _imageSizes_ `Array`: Available image sizes
- _maxWidth_ `number`: Max width to constraint resizing
- _allowedBlockTypes_ `boolean|Array`: Allowed block types
- _hasFixedToolbar_ `boolean`: Whether or not the editor toolbar is fixed
- _focusMode_ `boolean`: Whether the focus mode is enabled or not
- _styles_ `Array`: Editor Styles
- _keepCaretInsideBlock_ `boolean`: Whether caret should move between blocks in edit mode
- _bodyPlaceholder_ `string`: Empty post placeholder
- _titlePlaceholder_ `string`: Empty title placeholder
- _codeEditingEnabled_ `boolean`: Whether or not the user can switch to the code editor
- _\_\_experimentalCanUserUseUnfilteredHTML_ `boolean`: Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes.
- _\_\_experimentalBlockDirectory_ `boolean`: Whether the user has enabled the Block Directory
- _\_\_experimentalBlockPatterns_ `Array`: Array of objects representing the block patterns
- _\_\_experimentalBlockPatternCategories_ `Array`: Array of objects representing the block pattern categories
<a name="SkipToSelectedBlock" href="#SkipToSelectedBlock">#</a> **SkipToSelectedBlock**
Undocumented declaration.
<a name="store" href="#store">#</a> **store**
Store definition for the block editor namespace.
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore>
_Type_
- `Object`
<a name="storeConfig" href="#storeConfig">#</a> **storeConfig**
Block editor data store configuration.
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#registerStore>
_Type_
- `Object`
<a name="ToolSelector" href="#ToolSelector">#</a> **ToolSelector**
Undocumented declaration.
<a name="transformStyles" href="#transformStyles">#</a> **transformStyles**
Applies a series of CSS rule transforms to wrap selectors inside a given class and/or rewrite URLs depending on the parameters passed.
_Parameters_
- _styles_ `Array`: CSS rules.
- _wrapperClassName_ `string`: Wrapper Class Name.
_Returns_
- `Array`: converted rules.
<a name="Typewriter" href="#Typewriter">#</a> **Typewriter**
Ensures that the text selection keeps the same vertical distance from the
viewport during keyboard events within this component. The vertical distance
can vary. It is the last clicked or scrolled to position.
<a name="URLInput" href="#URLInput">#</a> **URLInput**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/url-input/README.md>
<a name="URLInputButton" href="#URLInputButton">#</a> **URLInputButton**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/url-input/README.md>
<a name="URLPopover" href="#URLPopover">#</a> **URLPopover**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/url-popover/README.md>
<a name="useBlockDisplayInformation" href="#useBlockDisplayInformation">#</a> **useBlockDisplayInformation**
Hook used to try to find a matching block variation and return
the appropriate information for display reasons. In order to
to try to find a match we need to things:
1\. Block's client id to extract it's current attributes.
2\. A block variation should have set `isActive` prop to a proper function.
If for any reason a block variaton match cannot be found,
the returned information come from the Block Type.
If no blockType is found with the provided clientId, returns null.
_Parameters_
- _clientId_ `string`: Block's client id.
_Returns_
- `?WPBlockDisplayInformation`: Block's display information, or `null` when the block or its type not found.
<a name="useBlockEditContext" href="#useBlockEditContext">#</a> **useBlockEditContext**
Undocumented declaration.
<a name="useBlockProps" href="#useBlockProps">#</a> **useBlockProps**
This hook is used to lightly mark an element as a block element. The element
should be the outermost element of a block. Call this hook and pass the
returned props to the element to mark as a block. If you define a ref for the
element, it is important to pass the ref to this hook, which the hook in turn
will pass to the component through the props it returns. Optionally, you can
also pass any other props through this hook, and they will be merged and
returned.
_Parameters_
- _props_ `Object`: Optional. Props to pass to the element. Must contain the ref if one is defined.
- _options_ `Object`: Options for internal use only.
- _options.\_\_unstableIsHtml_ `boolean`:
_Returns_
- `Object`: Props to pass to the element to mark as a block.
<a name="validateThemeColors" href="#validateThemeColors">#</a> **validateThemeColors**
Given an array of theme colors checks colors for validity
_Parameters_
- _colors_ `Array`: The array of theme colors
_Returns_
- `Array`: The array of valid theme colors or the default colors
<a name="validateThemeGradients" href="#validateThemeGradients">#</a> **validateThemeGradients**
Given an array of theme gradients checks gradients for validity
_Parameters_
- _gradients_ `Array`: The array of theme gradients
_Returns_
- `Array`: The array of valid theme gradients or the default gradients
<a name="Warning" href="#Warning">#</a> **Warning**
_Related_
- <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/warning/README.md>
<a name="withColorContext" href="#withColorContext">#</a> **withColorContext**
Undocumented declaration.
<a name="withColors" href="#withColors">#</a> **withColors**
A higher-order component, which handles color logic for class generation color value, retrieval and color attribute setting.
For use with the default editor/theme color palette.
_Usage_
```jsx
export default compose(
withColors( 'backgroundColor', { textColor: 'color' } ),
MyColorfulComponent,
);
```
_Parameters_
- _colorTypes_ `...(Object|string)`: The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color.
_Returns_
- `Function`: Higher-order component.
<a name="withFontSizes" href="#withFontSizes">#</a> **withFontSizes**
Higher-order component, which handles font size logic for class generation,
font size value retrieval, and font size change handling.
_Parameters_
- _fontSizeNames_ `...(Object|string)`: The arguments should all be strings. Each string contains the font size attribute name e.g: 'fontSize'.
_Returns_
- `Function`: Higher-order component.
<a name="WritingFlow" href="#WritingFlow">#</a> **WritingFlow**
Handles selection and navigation across blocks. This component should be
wrapped around BlockList.
_Parameters_
- _props_ `Object`: Component properties.
- _props.children_ `WPElement`: Children to be rendered.
<!-- END TOKEN(Autogenerated API docs) -->
<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>