简介

在 TableCrud 表格渲染器中，addHeaderRenderComponent 和 addHeaderUrlComponent 是两个强大的头部页面渲染方法，它们可以混合使用，在表格头部展示自定义的 DIV+CSS 定制页面，适用于展示统计信息、通知公告、自定义组件等场景。

核心方法对比

方法名	渲染方式	适用场景	数据来源
`addHeaderRenderComponent`	直接模板渲染	静态内容、已知变量数据	本地PHP变量
`addHeaderUrlComponent`	远程URL渲染	动态内容、需要异步加载的数据	远程API接口

方法详解

一、模板直接渲染

方法签名

public function addHeaderRenderComponent(
    string $template,  // HTML模板内容
    array $vars = [],  // 模板变量
    array $option = [] // 组件配置选项
): Component

参数说明

参数名	类型	默认值	必填	说明
template	string	-	✓	HTML模板内容，支持变量绑定语法 `${变量名}`
vars	array	[]	✗	模板变量数组，用于替换模板中的变量占位符
option	array	[]	✗	组件额外配置选项

二、远程异步渲染

方法签名

public function addHeaderUrlComponent(
    string $url,       // 远程组件接口地址
    array $vars = [],  // 附带变量参数
    array $option = [] // 组件配置选项
): Component

参数说明

参数名	类型	默认值	必填	说明
url	string	-	✓	远程组件接口地址，返回符合 AMIS Schema 规范的JSON数据
vars	array	[]	✗	附带变量参数，会作为请求参数发送到接口
option	array	[]	✗	组件额外配置选项

返回值

返回 Component 对象实例，可以链式调用配置方法。

工作原理

创建 Component 组件实例（类型为 XbRemote）
自动添加默认样式类 xb-header-component
将 URL 和变量参数绑定到组件
前端向指定 URL 发起请求，动态加载组件内容

接口返回格式要求

方式一：返回 AMIS Schema

{
  "status": 0,
  "msg": "success",
  "data": {
    "type": "div",
    "className": "custom-class",
    "body": "组件内容"
  }
}

方式二：返回完整 AMIS 组件

{
  "status": 0,
  "msg": "success",
  "data": {
    "type": "cards",
    "source": "$items",
    "card": {
      "body": [
        {
          "type": "tpl",
          "tpl": "标题：${title}"
        }
      ]
    }
  }
}

混合使用示例

示例一：基础混合使用

Builder::crud(function(TableCrud $builder) {
  // 1. 添加静态公告（模板渲染）
  $notice = <<<HTML
<div class="alert alert-info">
  <i class="fa fa-info-circle"></i> 
  <strong>系统通知：</strong>新功能已上线，欢迎体验！
</div>
HTML;
  $builder->addHeaderRenderComponent($notice);
  
  // 2. 添加远程统计数据（URL渲染）
  $builder->addHeaderUrlComponent('/api/statistics', [
    'date_range' => 'today'
  ]);
  
  // 3. 添加快捷操作按钮（模板渲染）
  $actions = <<<HTML
<div class="quick-actions">
  <button class="btn btn-primary" onclick="exportData()">导出数据</button>
  <button class="btn btn-success" onclick="importData()">导入数据</button>
</div>
HTML;
  $builder->addHeaderRenderComponent($actions);
  
  // 表格配置...
  $builder->setUrl('/api/data');
});

示例二：带变量的模板渲染

Builder::crud(function(TableCrud $builder) {
  // 自定义头部统计信息
  $template = <<<HTML
<div class="header" style="background-color: #f5f5f5; padding: 10px; border-radius: 5px;">
  <span class="text" style="font-size: 16px; color: red;">
    我是可以自定义的头部 - 总记录数: \${totalCount}
  </span>
</div>
HTML;
  
  $builder->addHeaderRenderComponent($template, [
    'totalCount' => 1000
  ]);
});

示例三：Vue 组件模板

根据您提供的截图代码，这是一个完整的 Vue 组件示例：

Builder::crud(function(TableCrud $builder) {
  $vueTemplate = <<<HTML
<script>
export default {
  data() {
    return {
      message: '我是可以自定义的头部'
    }
  },
  methods: {
    handleClick() {
      alert(this.message);
    }
  }
}
</script>

<template>
  <div class="header">
    <span class="text">{{ message }}</span>
  </div>
</template>

<style lang="scss" scoped>
.header {
  background-color: #f5f5f5;
  padding: 10px;
  border-radius: 5px;
  
  .text {
    font-size: 16px;
    color: red;
  }
}
</style>
HTML;
  
  $builder->addHeaderRenderComponent($vueTemplate);
});

示例四：高级混合应用（多种组件组合）

Builder::crud(function(TableCrud $builder) {
  // 1. 页面提示信息
  $builder->addHeaderRenderComponent(
    '<div class="alert alert-warning">
      <i class="fa fa-exclamation-triangle"></i> 
      系统将于今晚 22:00-24:00 进行维护
    </div>'
  );
  
  // 2. 远程统计卡片（动态数据）
  $builder->addHeaderUrlComponent('/api/dashboard', [
    'module' => 'orders',
    'period' => 'today'
  ], function($component) {
    $component->className('xb-header-component dashboard-panel');
  });
  
  // 3. 自定义统计面板（本地数据）
  $statsTemplate = <<<HTML
<div class="stats-row" style="display: flex; gap: 20px; padding: 15px; background: #fff; border-radius: 4px;">
  <div class="stat-item" style="flex: 1; text-align: center;">
    <div style="font-size: 12px; color: #999;">总用户数</div>
    <div style="font-size: 24px; color: #333; font-weight: bold;">\${totalUsers}</div>
  </div>
  <div class="stat-item" style="flex: 1; text-align: center;">
    <div style="font-size: 12px; color: #999;">今日新增</div>
    <div style="font-size: 24px; color: #52c41a; font-weight: bold;">\${todayNew}</div>
  </div>
  <div class="stat-item" style="flex: 1; text-align: center;">
    <div style="font-size: 12px; color: #999;">活跃用户</div>
    <div style="font-size: 24px; color: #1890ff; font-weight: bold;">\${activeUsers}</div>
  </div>
</div>
HTML;
  
  $builder->addHeaderRenderComponent($statsTemplate, [
    'totalUsers' => 5000,
    'todayNew' => 120,
    'activeUsers' => 3200
  ]);
  
  // 4. 快捷操作区
  $builder->addHeaderRenderComponent(
    '<div style="text-align: right; padding: 10px;">
      <button class="btn btn-sm btn-primary">批量导入</button>
      <button class="btn btn-sm btn-success">批量导出</button>
      <button class="btn btn-sm btn-danger">批量删除</button>
    </div>'
  );
});

组件属性配置

Component 对象可用方法

$component = $builder->addHeaderRenderComponent('<div>内容</div>');

// 设置自定义CSS类名
$component->className('custom-header my-component');

// 设置额外变量（适用于 URL 渲染）
$component->setVariable('refresh', 60); // 60秒自动刷新
$component->setVariable('autoLoad', true);

// 批量设置变量
$component->setVariables([
  'theme' => 'dark',
  'showTitle' => true
]);

使用场景总结

场景	推荐方法	原因
系统公告通知	addHeaderRenderComponent	内容固定，无需异步加载
实时统计数据	addHeaderUrlComponent	数据动态变化，需要异步获取
快捷操作按钮	addHeaderRenderComponent	静态按钮，绑定前端事件即可
数据分析图表	addHeaderUrlComponent	图表数据需要后端计算
用户权限提示	addHeaderRenderComponent	基于PHP权限判断即可
定时刷新内容	addHeaderUrlComponent	支持动态刷新机制
Vue/React组件	addHeaderRenderComponent	直接渲染前端组件代码
多接口数据聚合	addHeaderUrlComponent	后端聚合多个数据源

核心特性

1. 顺序渲染

组件按照添加顺序依次渲染，先添加的在上方显示。

2. 样式隔离

每个组件自动添加 xb-header-component 类名，方便统一样式管理。

3. 变量绑定

模板渲染支持 ${变量名} 语法进行变量替换。

4. 混合使用

两种方法可以任意组合使用，实现复杂的头部布局。

5. 响应式支持

可以配合 Bootstrap 等框架实现响应式布局。

注意事项

渲染顺序：头部组件会在表格上方按添加顺序依次显示
样式管理：默认添加 xb-header-component 类名，建议为不同类型组件设置不同的自定义类名
变量语法：模板渲染使用 ${变量名} 语法，URL渲染的接口返回数据也支持此语法
性能考虑：频繁更新的数据建议使用 URL 渲染，避免每次都重新生成整个页面
安全性：模板内容如果包含用户输入，请确保已进行 XSS 防护处理
接口规范：URL 渲染的接口必须返回符合 AMIS Schema 规范的 JSON 数据
组件数量：理论上可以添加任意数量的头部组件，但建议不超过 5 个以保持页面简洁