@wordpress/blocks
Version:
Block API for WordPress.
461 lines • 15.6 kB
TypeScript
import type { BlockType, Block, BlockVariation, BlockVariationScope, BlockStyle, BlockBindingsSource, Icon, BlockConfiguration } from '../types';
/**
* Sets the server side block definition of blocks.
*
* Ignored from documentation due to being marked as unstable.
*
* @ignore
*
* @param definitions Server-side block definitions
*/
export declare function unstable__bootstrapServerSideBlockDefinitions(definitions: Record<string, Record<string, unknown>>): void;
/**
* Registers a new block provided a unique name and an object defining its
* behavior. Once registered, the block is made available as an option to any
* editor interface where blocks are implemented.
*
* For more in-depth information on registering a custom block see the
* [Create a block tutorial](https://developer.wordpress.org/block-editor/getting-started/create-block/).
*
* @param blockNameOrMetadata Block type name or its metadata.
* @param settings Block settings.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { registerBlockType } from '@wordpress/blocks'
*
* registerBlockType( 'namespace/block-name', {
* title: __( 'My First Block' ),
* edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
* save: () => <div>Hello from the saved content!</div>,
* } );
* ```
*
* @return The block, if it has been successfully registered;
* otherwise `undefined`.
*/
export declare function registerBlockType<Attributes extends Record<string, unknown> = Record<string, unknown>>(blockNameOrMetadata: BlockConfiguration<Attributes>, settings?: Partial<BlockConfiguration<Attributes>>): BlockType | undefined;
export declare function registerBlockType<Attributes extends Record<string, unknown> = Record<string, unknown>>(blockNameOrMetadata: string, settings: BlockConfiguration<Attributes>): BlockType | undefined;
/**
* Registers a new block collection to group blocks in the same namespace in the inserter.
*
* @param namespace The namespace to group blocks by in the inserter; corresponds to the block namespace.
* @param settings The block collection settings.
* @param settings.title The title to display in the block inserter.
* @param settings.icon The icon to display in the block inserter.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { registerBlockCollection, registerBlockType } from '@wordpress/blocks';
*
* // Register the collection.
* registerBlockCollection( 'my-collection', {
* title: __( 'Custom Collection' ),
* } );
*
* // Register a block in the same namespace to add it to the collection.
* registerBlockType( 'my-collection/block-name', {
* title: __( 'My First Block' ),
* edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
* save: () => <div>'Hello from the saved content!</div>,
* } );
* ```
*/
export declare function registerBlockCollection(namespace: string, { title, icon }: {
title: string;
icon?: Icon;
}): void;
/**
* Unregisters a block collection
*
* @param namespace The namespace to group blocks by in the inserter; corresponds to the block namespace
*
* @example
* ```js
* import { unregisterBlockCollection } from '@wordpress/blocks';
*
* unregisterBlockCollection( 'my-collection' );
* ```
*/
export declare function unregisterBlockCollection(namespace: string): void;
/**
* Unregisters a block.
*
* @param name Block name.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { unregisterBlockType } from '@wordpress/blocks';
*
* const ExampleComponent = () => {
* return (
* <Button
* onClick={ () =>
* unregisterBlockType( 'my-collection/block-name' )
* }
* >
* { __( 'Unregister my custom block.' ) }
* </Button>
* );
* };
* ```
*
* @return The previous block value, if it has been successfully
* unregistered; otherwise `undefined`.
*/
export declare function unregisterBlockType(name: string): BlockType | undefined;
/**
* Assigns name of block for handling non-block content.
*
* @param blockName Block name.
*/
export declare function setFreeformContentHandlerName(blockName: string): void;
/**
* Retrieves name of block handling non-block content, or undefined if no
* handler has been defined.
*
* @return Block name.
*/
export declare function getFreeformContentHandlerName(): string | null;
/**
* Retrieves name of block used for handling grouping interactions.
*
* @return Block name.
*/
export declare function getGroupingBlockName(): string | null;
/**
* Assigns name of block handling unregistered block types.
*
* @param blockName Block name.
*/
export declare function setUnregisteredTypeHandlerName(blockName: string): void;
/**
* Retrieves name of block handling unregistered block types, or undefined if no
* handler has been defined.
*
* @return Block name.
*/
export declare function getUnregisteredTypeHandlerName(): string | null;
/**
* Assigns the default block name.
*
* @param name Block name.
*
* @example
* ```js
* import { setDefaultBlockName } from '@wordpress/blocks';
*
* const ExampleComponent = () => {
*
* return (
* <Button onClick={ () => setDefaultBlockName( 'core/heading' ) }>
* { __( 'Set the default block to Heading' ) }
* </Button>
* );
* };
* ```
*/
export declare function setDefaultBlockName(name: string): void;
/**
* Assigns name of block for handling block grouping interactions.
*
* This function lets you select a different block to group other blocks in instead of the
* default `core/group` block. This function must be used in a component or when the DOM is fully
* loaded. See https://developer.wordpress.org/block-editor/reference-guides/packages/packages-dom-ready/
*
* @param name Block name.
*
* @example
* ```js
* import { setGroupingBlockName } from '@wordpress/blocks';
*
* const ExampleComponent = () => {
*
* return (
* <Button onClick={ () => setGroupingBlockName( 'core/columns' ) }>
* { __( 'Wrap in columns' ) }
* </Button>
* );
* };
* ```
*/
export declare function setGroupingBlockName(name: string): void;
/**
* Retrieves the default block name.
*
* @return Block name.
*/
export declare function getDefaultBlockName(): string | null;
/**
* Returns a registered block type.
*
* @param name Block name.
*
* @return Block type.
*/
export declare function getBlockType(name: string): BlockType | undefined;
/**
* Returns all registered blocks.
*
* @return Block settings.
*/
export declare function getBlockTypes(): BlockType[];
/**
* Returns the block support value for a feature, if defined.
*
* @param nameOrType Block name or type object
* @param feature Feature to retrieve
* @param defaultSupports Default value to return if not
* explicitly defined
*
* @return Block support value
*/
export declare function getBlockSupport(nameOrType: string | BlockType, feature: string, defaultSupports?: unknown): unknown;
/**
* Returns true if the block defines support for a feature, or false otherwise.
*
* @param nameOrType Block name or type object.
* @param feature Feature to test.
* @param defaultSupports Whether feature is supported by
* default if not explicitly defined.
*
* @return Whether block supports feature.
*/
export declare function hasBlockSupport(nameOrType: string | BlockType, feature: string, defaultSupports?: boolean): boolean;
/**
* Determines whether or not the given block is a reusable block. This is a
* special block type that is used to point to a global block stored via the
* API.
*
* @param blockOrType Block or Block Type to test.
*
* @return Whether the given block is a reusable block.
*/
export declare function isReusableBlock(blockOrType: Block | BlockType | null | undefined): boolean;
/**
* Determines whether or not the given block is a template part. This is a
* special block type that allows composing a page template out of reusable
* design elements.
*
* @param blockOrType Block or Block Type to test.
*
* @return Whether the given block is a template part.
*/
export declare function isTemplatePart(blockOrType: Block | BlockType | null | undefined): boolean;
/**
* Returns an array with the child blocks of a given block.
*
* @param blockName Name of block (example: “latest-posts”).
*
* @return Array of child block names.
*/
export declare const getChildBlockNames: (blockName: string) => string[];
/**
* Returns a boolean indicating if a block has child blocks or not.
*
* @param blockName Name of block (example: “latest-posts”).
*
* @return True if a block contains child blocks and false otherwise.
*/
export declare const hasChildBlocks: (blockName: string) => boolean;
/**
* Returns a boolean indicating if a block has at least one child block with inserter support.
*
* @param blockName Block type name.
*
* @return True if a block contains at least one child blocks with inserter support
* and false otherwise.
*/
export declare const hasChildBlocksWithInserterSupport: (blockName: string) => boolean;
/**
* Registers a new block style for the given block types.
*
* For more information on connecting the styles with CSS
* [the official documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/#styles).
*
* @param blockNames Name of blocks e.g. “core/latest-posts” or `[“core/group”, “core/columns”]`.
* @param styleVariation Object containing `name` which is the class name applied to the block and `label` which identifies the variation to the user.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { registerBlockStyle } from '@wordpress/blocks';
* import { Button } from '@wordpress/components';
*
*
* const ExampleComponent = () => {
* return (
* <Button
* onClick={ () => {
* registerBlockStyle( 'core/quote', {
* name: 'fancy-quote',
* label: __( 'Fancy Quote' ),
* } );
* } }
* >
* { __( 'Add a new block style for core/quote' ) }
* </Button>
* );
* };
* ```
*/
export declare const registerBlockStyle: (blockNames: string | string[], styleVariation: BlockStyle | BlockStyle[]) => void;
/**
* Unregisters a block style for the given block.
*
* @param blockName Name of block (example: “core/latest-posts”).
* @param styleVariationName Name of class applied to the block.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { unregisterBlockStyle } from '@wordpress/blocks';
* import { Button } from '@wordpress/components';
*
* const ExampleComponent = () => {
* return (
* <Button
* onClick={ () => {
* unregisterBlockStyle( 'core/quote', 'plain' );
* } }
* >
* { __( 'Remove the "Plain" block style for core/quote' ) }
* </Button>
* );
* };
* ```
*/
export declare const unregisterBlockStyle: (blockName: string, styleVariationName: string) => void;
/**
* Returns an array with the variations of a given block type.
* Ignored from documentation as the recommended usage is via useSelect from @wordpress/data.
*
* @ignore
*
* @param blockName Name of block (example: “core/columns”).
* @param scope Block variation scope name.
*
* @return Block variations.
*/
export declare const getBlockVariations: (blockName: string, scope?: BlockVariationScope) => BlockVariation[] | void;
/**
* Registers a new block variation for the given block type.
*
* For more information on block variations see
* [the official documentation ](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/).
*
* @param blockName Name of the block (example: “core/columns”).
* @param variation Object describing a block variation.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { registerBlockVariation } from '@wordpress/blocks';
* import { Button } from '@wordpress/components';
*
* const ExampleComponent = () => {
* return (
* <Button
* onClick={ () => {
* registerBlockVariation( 'core/embed', {
* name: 'custom',
* title: __( 'My Custom Embed' ),
* attributes: { providerNameSlug: 'custom' },
* } );
* } }
* >
* __( 'Add a custom variation for core/embed' ) }
* </Button>
* );
* };
* ```
*/
export declare const registerBlockVariation: (blockName: string, variation: BlockVariation | BlockVariation[]) => void;
/**
* Unregisters a block variation defined for the given block type.
*
* @param blockName Name of the block (example: “core/columns”).
* @param variationName Name of the variation defined for the block.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { unregisterBlockVariation } from '@wordpress/blocks';
* import { Button } from '@wordpress/components';
*
* const ExampleComponent = () => {
* return (
* <Button
* onClick={ () => {
* unregisterBlockVariation( 'core/embed', 'youtube' );
* } }
* >
* { __( 'Remove the YouTube variation from core/embed' ) }
* </Button>
* );
* };
* ```
*/
export declare const unregisterBlockVariation: (blockName: string, variationName: string | string[]) => void;
/**
* Registers a new block bindings source with an object defining its
* behavior. Once registered, the source is available to be connected
* to the supported block attributes.
*
* @since 6.7.0 Introduced in WordPress core.
*
* @param source Object describing a block bindings source.
*
* @example
* ```js
* import { _x } from '@wordpress/i18n';
* import { registerBlockBindingsSource } from '@wordpress/blocks'
*
* registerBlockBindingsSource( {
* name: 'plugin/my-custom-source',
* label: _x( 'My Custom Source', 'block bindings source' ),
* usesContext: [ 'postType' ],
* getValues: getSourceValues,
* setValues: updateMyCustomValuesInBatch,
* canUserEditValue: () => true,
* } );
* ```
*/
export declare const registerBlockBindingsSource: (source: BlockBindingsSource) => void;
/**
* Unregisters a block bindings source by providing its name.
*
* @since 6.7.0 Introduced in WordPress core.
*
* @param name The name of the block bindings source to unregister.
*
* @example
* ```js
* import { unregisterBlockBindingsSource } from '@wordpress/blocks';
*
* unregisterBlockBindingsSource( 'plugin/my-custom-source' );
* ```
*/
export declare function unregisterBlockBindingsSource(name: string): void;
/**
* Returns a registered block bindings source by its name.
*
* @since 6.7.0 Introduced in WordPress core.
*
* @param name Block bindings source name.
*
* @return Block bindings source.
*/
export declare function getBlockBindingsSource(name: string): BlockBindingsSource | undefined;
/**
* Returns all registered block bindings sources.
*
* @since 6.7.0 Introduced in WordPress core.
*
* @return Block bindings sources.
*/
export declare function getBlockBindingsSources(): Record<string, BlockBindingsSource>;
//# sourceMappingURL=registration.d.ts.map