Gutenberg Blocks

WordPress 5 通过其名为 Gutenberg 的新编辑器引入了新的内容创建体验。

Gutenberg 是一个基于块的编辑器,它提供了一种更好、更自然的方式来在您的网站上创建新内容。 使用 Carbon Fields v3,我们为您服务,您可以开始为您的网站创建令人惊叹的块。

为了创建一个新的 Gutenberg Block,您仍然可以使用已经熟悉的对开发人员友好的方式,就像您注册任何其他容器一样。

<?php

use Carbon_Fields\Block;
use Carbon_Fields\Field;

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_render_callback( function ( $fields, $attributes, $inner_blocks ) {
		?>

		<div class="block">
			<div class="block__heading">
				<h1><?php echo esc_html( $fields['heading'] ); ?></h1>
			</div><!-- /.block__heading -->

			<div class="block__image">
				<?php echo wp_get_attachment_image( $fields['image'], 'full' ); ?>
			</div><!-- /.block__image -->

			<div class="block__content">
				<?php echo apply_filters( 'the_content', $fields['content'] ); ?>
			</div><!-- /.block__content -->
		</div><!-- /.block -->

		<?php
	} );
注意 ->set_render_callback() 方法。 这允许您在预览模式和前端设置将从该块生成的输出。
  • ->set_render_callback() 接受一个回调,它应该输出块的 HTML 标记。 回调函数将使用以下参数调用:
  • $fields,一个包含块中输入数据的数组。
  • $attributes,一个包含块属性的数组,例如自定义 CSS 类、对齐方式等。
  • $inner_blocks,一个包含所有嵌套块内容的字符串。

配置方法

set_description( $description )

此方法允许您设置描述块的简短文本。 一旦您关注块,描述就会显示在块检查器侧栏中。

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_description( __( 'A simple block consisting of a heading, an image and a text content.' ) )
	->set_render_callback( function () {
		// ..
	} );

set_category( $slug, $title = null, $icon = null )

古腾堡块可以分为不同的类别。 默认情况下,以下是开箱即用的注册:

  • common
  • formatting
  • layout
  • widgets
  • embed

如果您不指定类别,则该块将分配给common

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_category( 'layout' )
	->set_render_callback( function () {
		// ..
	} );

但是,如果需要,您可以为您的块注册一个新类别。

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_category( 'custom-category', __( 'Custom Category' ), 'smiley' )
	->set_render_callback( function () {
		// ..
	} );

$icon 参数接受 WordPress Dashicon 的 slug.

set_icon( $icon )

除了为块类别设置图标外,您还可以为块本身设置图标。

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_icon( 'heart' )
	->set_render_callback( function () {
		// ..
	} );

set_keywords( $keywords = [] )

此方法允许您设置别名以帮助用户在搜索时发现它。

!> 每个区块最多只能添加 3 个关键字。

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_keywords( [ __( 'block' ), __( 'image' ), __( 'content' ) ] )
	->set_render_callback( function () {
		// ..
	} );

set_mode( $mode = 'edit' )

此方法将块模式设置为“编辑”或“两者”。

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_mode( 'edit' )
	->set_render_callback( function () {
		// ..
	} );

!> 嵌套块不受此方法影响。 只有他们的父母可以进入预览模式。

set_editor_style( $handle )

您可以为您的块设置自定义样式表,该样式表将加载到管理面板的编辑器中。

wp_register_style(
	'crb-my-shiny-gutenberg-block-stylesheet',
	get_stylesheet_directory_uri() . '/css/gutenberg/my-shiny-gutenberg-block.css'
);

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_editor_style( 'crb-my-shiny-gutenberg-block-stylesheet' )
	->set_render_callback( function () {
		// ..
	} );

set_style( $handle )

此方法与 set_editor_style 相同,但是它也会在前端加载样式表。

wp_register_style(
	'crb-my-shiny-gutenberg-block-stylesheet',
	get_stylesheet_directory_uri() . '/css/gutenberg/my-shiny-gutenberg-block.css'
);

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_style( 'crb-my-shiny-gutenberg-block-stylesheet' )
	->set_render_callback( function () {
		// ..
	} );

set_inner_blocks( $inner_blocks = true )

此方法控制块包含嵌套块的能力。

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_render_callback( function () {
		// ..
	} );

set_inner_blocks_position( $position = 'above' )

此方法设置内部块将呈现的位置。 可能的值是:abovebelow

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_inner_blocks_position( 'below' )
	->set_render_callback( function () {
		// ..
	} );

set_inner_blocks_template( $template = null )

此方法允许您设置块的模板,您的块的每个新实例都将包含该模板。 可能的值为:数组和空值。

有关详细信息,请参阅古腾堡 > 模板

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_inner_blocks_template( array(
		array( 'core/heading' ),
		array( 'core/paragraph' )
	) )
	->set_render_callback( function () {
		// ..
	} );

set_inner_blocks_template_lock( $lock = null )

此方法允许您锁定包含嵌套块的区域。 可能的值是:

  • all - 阻止所有操作。 无法插入新块。 移动现有块或删除它们。
  • insert - 防止插入或删除块,但允许移动现有块。
  • false - 即使父块包含锁定,也防止将锁定应用于嵌套块区域。
  • null - 禁用应用于该区域的任何锁。

有关更多详细信息,请参阅 Gutenberg > TemplatesGutenberg > Inner Blocks

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_inner_blocks_template( array(
		array( 'core/heading' ),
		array( 'core/paragraph' )
	) )
	->set_inner_blocks_template_lock( 'insert' )
	->set_render_callback( function () {
		// ..
	} );

set_parent( $parent = null )

此方法允许您将要插入的块限制为特定的块类型。 可能的值为 - 字符串、数组或 null。

有关更多详细信息,请参阅古腾堡 > 块注册

Block::make( __( 'Product' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_render_callback( function () {
		// ..
	} );

Block::make( __( 'Product Description' ) )
	->add_fields( array(
		// ...
	) )
	->set_parent( 'carbon-fields/product' )
	->set_render_callback( function () {
		// ..
	} );

set_allowed_inner_blocks( $blocks = null )

此方法允许您限制可以插入嵌套块区域的块类型。 可能的值为 - 数组或 null。

有关详细信息,请参阅古腾堡 > 内部块

!> 如果传递了一个空数组,则只能插入以您的块为父块的块。 请参阅 set_parent 方法。

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_allowed_inner_blocks( array(
		'core/paragraph',
		'core/list'
	) )
	->set_render_callback( function () {
		// ..
	} );