原文链接: Block API in Drupal 8
概述
Drupal 8 的区块实际上是由两个独立的API结构组成的，延续了Drupal一直以来的用户体验。这两个API结构分别是：Block Plugin API，一个独立的可复用的API；区块实体API，用于区块控制位置和可见性。
通过Block Plugin API创建区块
在你自定义的模块代码中创建区块需要了解Plugin API，更具体的说是基于注解的插件探测(方式/模式)（原文： Annotations based plugin discovery）。这是Drupal 8用来查找你自定义的区块的机制。
在模块中创建自定义区块包含以下步骤：
- 使用注解创建一个区块插件
- 继承Drupal\block\BlockBase类
- 根据实际需要实现Drupal\block\BlockPluginInterface接口中的方法
让区块对Drupal和用户可见
假设你的模块叫 fax，依照PSR-4标准，你自定义的区块的代码应该放到 fax/src/Plugin/Block/之中，并基于它包含的类来命名。比如类名为 FaxBlock，那么文件层次应该像 fax/src/Plugin/Block/FaxBlock.php这样。
在 FaxBlock.php中定义一个名为 FaxBlock的类,如下例:
<?php
namespace Drupal\fax\Plugin\Block;
use Drupal\block\BlockBase;
/**
* Provides a 'Fax' block.
*
* @Block(
* id = "fax_block",
* admin_label = @Translation("Fax block"),
* )
*/
class ChadBlock extends BlockBase {
// Override BlockPluginInterface methods here.
}
?>
注解中的'id'属性是你的区块的机读名称，唯一，能被其他代码引用。注解'admin_label'定义了显示名称。
两个最常重写的方法:
BlockPluginInterface::build()- 该方法返回一个渲染后的数组,包含你想要在区块中显示的内容。
BlockPluginInterface::access()- 该方法根据自定逻辑控制区块的可见性。
添加自定义配置选项
你可以通过重写 BlockPluginInterface::blockForm()和 BlockPluginInterface::blockSubmit()方法，然后使用BlockBase::setConfigurationValue()和 BlockBase::getConfiguration()方法来添加自定义配置选项到区块当中。
下例，在blockForm()中添加了一个textfield，然后在blockSubmit()方法中保存了用户填入的值。在blockForm()方法中，你可以看到数据是如何被你的代码获取和使用的。
<?php
/**
* Provides a 'Fax' block.
*
* @Block(
* id = "fax_block",
* admin_label = @Translation("Fax block"),
* )
*/
class ChadBlock extends BlockBase {
// Access and build methods here ...
/**
* {@inheritdoc}
*/
public function blockForm($form, &$form_state) {
$form = parent::blockForm($form, $form_state);
//Retrieve existing configuration for this block.
$config = $this->getConfiguration();
// Add a form field to the existing block configuration form.
$form['fax_block_settings'] = array(
'#type' => 'textfield',
'#title' => t('Fax number'),
'#default_value' => isset($config['fax_block_settings']) ? $config['fax_block_settings'] : '',
);
return $form;
}
/**
* {@inheritdoc}
*/
public function blockSubmit($form, &$form_state) {
// Save our custom settings when the form is submitted.
$this->setConfigurationValue('fax_block_settings', $form_state['values']['fax_block_settings']);
}
}
?>
同样，你可以再build()方法中调用BlockBase::getConfiguration()方法来接收配置参数并显示给用户。也可以在access()方法中执行更复杂的逻辑来决定是否显示这些配置参数。