本文介绍如何在 Laravel 8+ 中通过 @include 指令配合参数传递，将图表区块（如 _chart-widget.blade.php）封装为可复用、可配置的 Blade 组件，实现跨页面灵活渲染不同数据与样式。
本文介绍如何在 laravel 8+ 中通过 `@include` 指令配合参数传递，将图表区块（如 `_chart-widget.blade.php`）封装为可复用、可配置的 blade 组件，实现跨页面灵活渲染不同数据与样式。
在构建仪表盘或多图表页面时，重复编写结构相似但变量（如标题、ID、数据源、CSS 类）不同的 HTML/Blade 代码不仅降低开发效率，更增加维护成本。Laravel 提供了轻量而强大的 @include 机制，完美解决这一问题——它允许你将通用 UI 片段提取为独立 Blade 文件，并在引入时动态传入上下文变量，从而实现真正意义上的「一次编写、多处复用、按需定制」。
✅ 正确使用 @include 实现参数化复用
首先，确保你的可复用图表模板（例如 resources/views/components/_chart-widget.blade.php）采用空安全访问（null coalescing） 和默认值兜底策略，使所有关键变量均可被外部覆盖：
<!-- resources/views/components/_chart-widget.blade.php -->
<div class="card {{ $class ?? 'card-flush' }}">
<div class="card-header border-0 pt-5">
<h3 class="card-title align-items-start flex-column">
<span class="card-label fw-bolder fs-3 mb-1">{{ $title ?? 'Chart Title' }}</span>
<span class="text-muted fw-bold fs-7">{{ $subtitle ?? 'No description' }}</span>
</h3>
<div class="card-toolbar">
<button type="button"
class="btn btn-sm btn-icon btn-color-primary btn-active-light-primary"
data-kt-menu-trigger="click"
data-kt-menu-placement="bottom-end">
{!! theme()->getSvgIcon("icons/duotune/general/gen024.svg", "svg-icon-2") !!}
</button>
{{ theme()->getView('partials/menus/_menu-1') }}
</div>
</div>
<div class="card-body">
<div id="{{ $chartId ?? 'kt_charts_widget_default' }}" style="height: {{ $height ?? '350px' }}"></div>
</div>
</div>? 关键点：所有动态字段（$title, $subtitle, $chartId, $class, $height）均使用 ?? 运算符提供合理默认值，确保即使未传参也能安全渲染。
接着，在任意页面中按需引入并传入差异化参数：
{{-- 在 dashboard.blade.php 中渲染「用户增长图」 --}}
@include('components._chart-widget', [
'title' => 'User Acquisition',
'subtitle' => 'Last 30 days',
'chartId' => 'kt_chart_users',
'class' => 'card-xl-stretch mb-5 mb-xl-8',
'height' => '400px'
])
{{-- 同一页面中渲染「营收趋势图」 --}}
@include('components._chart-widget', [
'title' => 'Revenue Overview',
'subtitle' => 'Q3 2024 Performance',
'chartId' => 'kt_chart_revenue',
'class' => 'card-xl-stretch mb-5 mb-xl-8',
'height' => '380px'
])
{{-- 在 reports.blade.php 中复用，仅需变更数据上下文 --}}
@include('components._chart-widget', [
'title' => 'Conversion Rate',
'subtitle' => 'By Traffic Source',
'chartId' => 'kt_chart_conversion',
'class' => 'card-flush',
])⚠️ 注意事项与最佳实践
路径命名规范：建议将可复用组件存放在 resources/views/components/ 目录下，并以 _ 开头（如 _chart-widget.blade.php），明确标识其为私有片段（不会被直接路由访问）。
避免过度嵌套传参：若逻辑复杂（如需预处理数据、调用服务类），推荐升级为 Blade 组件（@component 或 @props） 或 自定义指令，而非在 @include 中塞入复杂 PHP 表达式。
-
JavaScript 初始化解耦：图表容器 ID（$chartId）动态化后，前端初始化脚本也需适配。推荐使用统一的初始化函数，接收容器 ID 作为参数：
// 在主布局中定义 function initChart(containerId, options) { const element = document.getElementById(containerId); if (element) new ApexCharts(element, options).render(); } // 在各页面中调用 initChart('kt_chart_users', { /* user chart config */ }); 性能提示：@include 是服务端包含，无额外 HTTP 请求开销；但若组件内含大量重复逻辑（如多次查询数据库），请确保数据已在父视图中预加载并传入，避免 N+1 渲染问题。
通过以上方式，你不仅能彻底告别重复代码，还能显著提升 UI 一致性与团队协作效率——同一图表骨架，千变万化的内容，尽在一行 @include 之间。
