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' )
此方法设置内部块将呈现的位置。 可能的值是:above
和below
。
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 > Templates 和 Gutenberg > 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 () {
// ..
} );