Drupal 7 hook_block_info() 和 hook_block_view() 在区块中输出信息

14/10/2025, by Ivan

在上一课中，我们为 Drupal 7 创建了一个模块，而在本课中，我们将继续扩展模块的功能。我们将通过 hook_block_view() 和 hook_block_info() 添加一个区块（block）输出。在这个区块中，将显示站点上最近注册的用户列表，并附带指向他们个人页面的链接。

我们先来看一下 hook_block_info() 的说明：

定义由模块创建的所有区块。

此钩子在 Drupal 中用于定义模块将输出哪些区块，同时还可以描述区块的显示设置。

在 hook_block_info() 中，模块的每个区块都会获得一个唯一的标识符 "delta"（即返回数组的键）。该 delta 值在模块中必须唯一，并用于以下场景：

作为参数传递给其他钩子，用于识别需要配置或输出的区块。
用于创建区块的 HTML 模板 “block-MODULE-DELTA”，以便 Drupal 对每个区块应用不同样式（可用于编写对应的 CSS 或 JavaScript）。
用于定义主题化函数 block__MODULE__DELTA，以实现更深入的主题定制。
用于在 hook_block_info_alter() 及其他钩子中识别该区块。

delta 的值可以是字符串或数字，最大长度为 32 字节。

返回值

返回一个关联数组，其键为每个区块的 delta，值为该区块的描述信息。每个区块的描述信息也是一个包含以下键值对的关联数组：

'info'：（必填）区块在后台显示的可读名称。此信息用于在管理界面“区块”部分识别该区块，不会显示在前台。

'cache'：（可选）定义区块的缓存行为。Drupal 支持以下缓存模式：

DRUPAL_CACHE_PER_ROLE（默认）：区块可根据查看页面的用户角色变化。
DRUPAL_CACHE_PER_USER：区块可根据不同用户变化。
DRUPAL_CACHE_PER_PAGE：区块可根据页面变化。
DRUPAL_CACHE_GLOBAL：区块在所有页面和用户中相同。

DRUPAL_NO_CACHE：区块不缓存。

'properties'：（可选）用于为区块添加附加元数据的数组。

常用的 properties 包括：

'administrative'：布尔值，指明区块是否用于后台管理环境。

'weight'：（可选）设置区块的权重。

'status'：（可选）设置区块状态（1 = 启用，0 = 禁用）。

'region'：（可选）设置区块所属的区域。

'visibility'：（可选）设置区块的可见性。可能的值包括：
- BLOCK_VISIBILITY_NOTLISTED：显示在除指定页面外的所有页面。
- BLOCK_VISIBILITY_LISTED：仅显示在指定页面。
- BLOCK_VISIBILITY_PHP：使用自定义 PHP 代码控制可见性。
'pages'：（可选）用于可见性参数的页面路径列表。

让我们通过钩子添加一个区块：

<?php
 
function sitemade_block_info(){
    $blocks = array();
    $blocks[1]['info'] = '用户列表';
    return $blocks;
}
 
?>

此区块应出现在后台“区块”管理中。我们将其添加到左侧边栏：

drupal block

现在，我们已经添加了一个区块，接下来通过钩子 hook_block_view() 输出它的内容。

hook_block_view($delta = '')：

参数

$delta — 表示当前钩子正在处理哪个区块。它是模块中在 hook_block_info() 定义的区块唯一标识符。

返回值

返回一个数组，包含以下元素：

subject：区块标题（默认情况下会自动翻译）。如果区块没有标题，则返回 NULL。

content：区块主体内容。可以是一个可渲染数组（推荐），也可以是包含 HTML 的字符串。

让我们添加这个钩子：

<?php
function sitemade_block_view($delta = ''){
    $block = array(); // 初始化空数组
    switch ($delta){
        case 1: // 与 hook_block_info() 中返回的 delta 相同
            $block['subject'] = '用户'; // 区块标题
            $block['content'] = ''; // 初始化内容字符串
            $query = db_select('users', 'u') // 查询用户表
                ->fields('u', array('uid', 'name')) // 选择字段
                ->orderBy('u.uid', 'DESC') // 按 ID 降序排列
                ->range(0, 5) // 仅取最近 5 个用户
                ->execute(); // 执行查询
            $users = $query->fetchAll(PDO::FETCH_ASSOC); // 以数组形式获取结果
            foreach($users as $user){
                $block['content'] .= '<div><a href="' . base_path() . 'user/' . $user['uid'] . '">' . $user['name'] . '</a></div>';
                // base_path() 函数返回网站根路径
            }
        break;
    }
    return $block;
}
?>

最终结果是：我们输出了站点上最近注册的 5 位用户列表，每个用户名都链接到其个人页面。当然，更好的做法是使用函数 l() 来生成链接，但这部分内容我们将在单独的章节中详细讲解。

Drupal list users

额外区块类型 (EBT) - 全新的布局构建器体验❗

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验

Drupal 7 hook_block_info() 和 hook_block_view() 在区块中输出信息

返回值

参数

返回值