头部页面渲染

简介

头部页面渲染组件用于在表格上方显示自定义内容，支持远程URL渲染和直接模板渲染两种方式，适用于展示统计信息、通知公告、自定义组件等场景。

用法示例

URL远程渲染

use plugin\xbCode\builder\Builder;

// 创建表格
Builder::crud(function($builder) {
  // 添加远程URL渲染组件
  $builder->addHeaderUrlComponent('/api/statistics');
});

带参数的URL渲染

Builder::crud(function($builder) {
  // 添加带参数的URL渲染
  $builder->addHeaderUrlComponent('/api/dashboard', [
    'type' => 'orders',
    'period' => 'today'
  ]);
  
  // 使用回调函数配置
  $builder->addHeaderUrlComponent('/api/stats', [], function($component) {
    $component->className('custom-header-stats');
  });
});

模板直接渲染

Builder::crud(function($builder) {
  // 直接渲染HTML模板
  $template = '<div class="alert alert-info">欢迎使用数据管理系统</div>';
  $builder->addHeaderRenderComponent($template);
  
  // 带变量的模板渲染
  $template = '<div class="stats-panel">总计: ${total} 条记录</div>';
  $builder->addHeaderRenderComponent($template, [
    'total' => 1000
  ]);
});

完整示例

Builder::crud(function($builder) {
  // 设置API接口
  $builder->setUrl('/api/users');
  
  // 添加统计信息渲染
  $builder->addHeaderUrlComponent('/api/user-stats', [
    'refresh' => true
  ], function($component) {
    $component->className('xb-user-stats');
  });
  
  // 添加公告信息
  $notice = '<div class="alert alert-warning">
    <strong>注意：</strong>系统将于今晚 22:00-24:00 进行维护
  </div>';
  $builder->addHeaderRenderComponent($notice);
  
  // 表格列配置
  $builder->addColumn('id', 'ID')->width(80);
  $builder->addColumn('username', '用户名');
});

效果图代码示例

效果图示例

可用方法

addHeaderUrlComponent 参数

addHeaderRenderComponent 参数

组件属性

URL渲染配置说明

URL渲染会向指定接口发送请求，接口应返回符合以下格式的JSON数据：

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

或者直接返回 AMIS Schema：

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

模板变量绑定

模板渲染支持使用 ${变量名} 语法绑定变量：

$template = '
<div class="stats-row">
  <div class="stat-item">
    <span class="label">总用户数：</span>
    <span class="value">${totalUsers}</span>
  </div>
  <div class="stat-item">
    <span class="label">今日新增：</span>
    <span class="value">${todayNew}</span>
  </div>
</div>
';

$builder->addHeaderRenderComponent($template, [
  'totalUsers' => 5000,
  'todayNew' => 120
]);

使用场景

• 数据统计展示（总数、今日新增等）
• 系统公告通知
• 操作提示信息
• 自定义图表展示
• 快捷操作面板
• 筛选条件说明
• 数据概览卡片

实际应用示例

统计卡片展示

Builder::crud(function($builder) {
  // 远程加载统计数据
  $builder->addHeaderUrlComponent('/api/order-statistics', [
    'date_range' => 'today'
  ]);
  
  $builder->setUrl('/api/orders');
  $builder->addColumn('order_sn', '订单号');
  $builder->addColumnStatus('status', '状态', [
    0 => '待支付',
    1 => '已支付',
    2 => '已完成'
  ]);
});

多个头部组件组合

Builder::crud(function($builder) {
  // 公告信息
  $notice = '<div class="alert alert-info">
    <i class="fa fa-info-circle"></i> 
    新功能已上线，欢迎体验！
  </div>';
  $builder->addHeaderRenderComponent($notice);
  
  // 统计信息
  $builder->addHeaderUrlComponent('/api/stats');
  
  // 快捷操作
  $actions = '<div class="quick-actions">
    <button class="btn btn-primary" onclick="exportData()">导出数据</button>
    <button class="btn btn-success" onclick="importData()">导入数据</button>
  </div>';
  $builder->addHeaderRenderComponent($actions);
  
  // 表格配置
  $builder->setUrl('/api/data');
});

注意事项

1. 头部组件会在表格上方按添加顺序依次显示
2. 默认添加 xb-header-component 类名用于样式控制
3. URL渲染的接口需要返回符合AMIS Schema规范的数据
4. 模板渲染支持HTML和AMIS Schema两种格式
5. 可以添加多个头部组件，它们会依次排列
6. 变量绑定使用 ${变量名} 语法
7. URL渲染支持动态数据更新
8. 建议为不同类型的头部组件设置不同的className以便样式定制

高级用法

响应式统计面板

$builder->addHeaderUrlComponent('/api/dashboard', [
  'module' => 'sales'
], function($component) {
  $component->className('xb-header-component dashboard-panel');
  $component->setVariable('reload', 60); // 60秒自动刷新
});

条件渲染

// 根据权限显示不同内容
$userRole = getCurrentUserRole();

if ($userRole === 'admin') {
  $builder->addHeaderRenderComponent(
    '<div class="admin-panel">管理员专属面板</div>'
  );
} else {
  $builder->addHeaderRenderComponent(
    '<div class="user-panel">用户信息面板</div>'
  );
}