changhorizon / bs5-renderers

v0.1.11 2026-08-13 09:45 UTC

Requires

• php: >=8.2

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.75
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^11.5

MIT

• Harper Chang

Published on Packagist.org on 2026-08-13 10:35 UTC

README

Bootstrap 5 HTML rendering components for admin panels

✨ 特性

• 🔗 Link button — 可设 href、style、size、disabled 状态
• 🎛️ Form button — 支持 type（submit/reset/button）、name、value、disabled
• 🍞 Breadcrumb — 面包屑导航，自动标记最后一项为 active
• 📊 Data list table — 平面数据表，支持可排序列头、空数据提示、行操作按钮
• 🌲 Data tree table — 递归树形表，支持展开/折叠、层级缩进
• ⚡ Row actions — 行操作按钮组，支持确认弹窗、图标

📦 安装

composer require changhorizon/bs5-renderers

📂 目录结构

src/
├── HtmlRenderers/
│   ├── Button/
│   │   ├── LinkButtonRenderer.php      # <a> 风格按钮
│   │   └── FormButtonRenderer.php      # <button> 风格表单按钮
│   ├── Nav/
│   │   └── BreadcrumbRenderer.php      # 面包屑导航
│   └── Table/
│       ├── TableHeadRenderer.php       # 表头（可排序）
│       ├── TableRowRenderer.php        # 数据行
│       ├── TableRowActionsRenderer.php # 行操作按钮列
│       ├── DataListRenderer.php        # 平面数据表
│       └── DataTreeRenderer.php        # 递归树形表
└── View/
    ├── LocaleRender.php                # locale 管理页面
    └── PageRender.php                  # CMS 页面管理

🚀 用法示例

Link Button

use ChangHorizon\BS5Renderers\HtmlChangHorizon\BS5Renderers\Button\LinkButtonRenderer;

$btn = (new LinkButtonRenderer())
    ->href('/admin/users/create')
    ->label('Add User')
    ->style('success')
    ->size('sm');

echo $btn->render();
// <a href="/admin/users/create" class="btn btn-success btn-sm" role="button">Add User</a>

Form Button

use ChangHorizon\BS5Renderers\HtmlChangHorizon\BS5Renderers\Button\FormButtonRenderer;

$btn = (new FormButtonRenderer())
    ->label('Delete')
    ->style('danger')
    ->name('action')
    ->value('delete');

echo $btn->render();
// <button type="submit" class="btn btn-danger" name="action" value="delete">Delete</button>

Breadcrumb

use ChangHorizon\BS5Renderers\HtmlChangHorizon\BS5Renderers\Nav\BreadcrumbRenderer;

$bc = (new BreadcrumbRenderer())
    ->add('Home', '/')
    ->add('Users', '/users')
    ->add('Edit');

echo $bc->render();
// <nav aria-label="breadcrumb"><ol class="breadcrumb">...

Data List Table

use ChangHorizon\BS5Renderers\HtmlChangHorizon\BS5Renderers\Table\DataListRenderer;

$table = new DataListRenderer();
$table->head()
    ->addColumn('Name', true, 'name')
    ->addColumn('Email', true, 'email')
    ->addColumn('Role');
$table->actions()
    ->add('Edit', '/users/1/edit', 'primary', 'pencil')
    ->add('Delete', '/users/1/delete', 'danger', 'trash', 'Are you sure?');
$table->data([
    ['name' => 'Alice', 'email' => '[e-mail]', 'role' => 'Admin'],
    ['name' => 'Bob', 'email' => '[e-mail]', 'role' => 'Editor'],
]);

echo $table->render();

Data Tree Table

use ChangHorizon\BS5Renderers\HtmlChangHorizon\BS5Renderers\Table\DataTreeRenderer;

$tree = new DataTreeRenderer();
$tree->head()->addColumn('Category')->addColumn('Slug');
$tree->tree([
    ['id' => '1', 'label' => 'Root', 'data' => ['slug' => 'root'], 'children' => [
        ['id' => '2', 'label' => 'Child A', 'data' => ['slug' => 'child-a'], 'children' => []],
        ['id' => '3', 'label' => 'Child B', 'data' => ['slug' => 'child-b'], 'children' => []],
    ]],
]);

echo $tree->render();

Page Render

use ChangHorizon\BS5Renderers\View\PageRender;

$page = new PageRender();
$page->breadcrumb()->add('Home', '/')->add('Pages');
$page->addButton()->href('/pages/create')->label('Add Page');
$page->tree()->head()->addColumn('Title')->addColumn('Status');
$page->tree()->tree([/* ... */]);

echo $page->render();
// 完整 Bootstrap 5 页面布局：面包屑 + 卡片 + 树形表格

📐 接口说明

所有 HtmlRenderer 类均使用流畅 setter 模式，链式调用后调用 render() 返回 HTML 字符串。

LinkButtonRenderer

方法	说明
href(string)	链接地址
label(string)	按钮文字
style(string)	Bootstrap 样式 (primary/success/danger/...)
size(string)	尺寸 (sm/lg)
disabled(bool)	禁用状态
attribute(name, value)	自定义 HTML 属性

DataListRenderer

方法	说明
head(): TableHeadRenderer	配置表头列
row(): TableRowRenderer	配置行
actions(): TableRowActionsRenderer	启用并配置操作按钮列
data(array)	设置数据行
emptyMessage(string)	空数据提示文字
tableClass(string)	表格 CSS 类

DataTreeRenderer

方法	说明
head(): TableHeadRenderer	配置表头列
tree(array)	设置树形数据
idKey(string)	节点 ID 字段名（默认 id）
labelKey(string)	节点标签字段名（默认 label）
childrenKey(string)	子节点字段名（默认 children）

🔍 静态分析

composer stan

🎯 代码风格

composer cs:chk    # check
composer cs:fix    # auto-fix

✅ 单元测试

composer test
composer test:coverage

🤝 贡献指南

欢迎 Issue 与 PR，建议遵循以下流程：

1. Fork 仓库
2. 创建新分支进行开发
3. 提交 PR 前请确保测试通过、风格一致
4. 提交详细描述

📜 License

MIT License. See the LICENSE file for details.