Laravel ChartJS 使用指南

1. 项目介绍

Laravel ChartJS 是一个基于 Chart.js 的 Laravel 包装器，用于简化在 Laravel 应用程序中使用图表的过程。Chart.js 是一个功能强大的、基于 JavaScript 的图表库，它提供了多种图表类型，如折线图、柱状图、饼图等。

2. 项目快速启动

首先，确保您的 Laravel 环境满足以下要求：

• Laravel 版本 9 或更高版本。
• Node.js 和 npm 用于编译前端资源。

安装

通过 Composer 安装 Laravel ChartJS：

composer require icehouse-ventures/laravel-chartjs

对于 Laravel 8 及以下版本，需要在 config/app.php 文件中注册服务提供者：

'providers' => [
    // ...
    IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider::class,
]

发布配置文件以便自定义设置（如 Chart.js 版本和文件交付方式）：

php artisan vendor:publish --provider="IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider" --tag="config"

安装 Chart.js

Laravel ChartJS 提供了多种安装 Chart.js 的方式：

• CDN：快速开发测试时，可以将配置文件中的 delivery 方法设置为 'CDN'，这样会通过外部内容分发网络加载指定的 Chart.js 文件。
• Publish：若不使用 JavaScript 包管理器，可以发布预编译的 Chart.js 文件到应用程序的公共文件夹。
• Binary：在特定情况下，可以选择直接从应用程序内部加载二进制文件，但不推荐这种方式。
• NPM：最佳实践是使用 NPM、Laravel Mix 或 Vite 将 Chart.js 包含在 JavaScript/CSS 打包流程中。

发布 Chart.js 资源文件的示例命令：

# 发布 Chart.js 版本 4 资源文件
php artisan vendor:publish --provider="IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider" --force --tag="assets"

# 发布 Chart.js 版本 3 资源文件
php artisan vendor:publish --provider="IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider" --force --tag="assets-v3"

# 发布 Chart.js 版本 2 资源文件
php artisan vendor:publish --provider="IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider" --force --tag="assets-v2"

使用

在控制器或路由中，使用 ChartJS Facade 创建图表：

use IcehouseVentures\LaravelChartjs\Facades\Chartjs;

$chart = Chartjs::build()
    ->name('myChart')
    ->type('line')
    ->size(600, 400)
    ->labels(['Label 1', 'Label 2', 'Label 3'])
    ->datasets([
        [
            'label' => 'Dataset 1',
            'data' => [10, 20, 30],
            'borderColor' => 'red',
            'fill' => false,
        ],
    ])
    ->options([
        'scales' => [
            'x' => [
                'title' => [
                    'display' => true,
                    'text' => 'X轴标题',
                ],
            ],
        ],
    ]);

在 Blade 视图中，显示图表：

<canvas id="{{ $chart->name }}" width="{{ $chart->width }}" height="{{ $chart->height }}"></canvas>

@push('scripts')
<script src="{{ asset('path/to/chart.js') }}"></script>
<script>
    new Chart(document.getElementById('{{ $chart->name }}'), {{ $chart->datasets|json }});
</script>
@endpush

3. 应用案例和最佳实践

• 在数据分析仪表板中使用折线图和柱状图展示实时数据。
• 在报告页面中使用饼图展示百分比分布。
• 使用配置选项 optionsRaw 方法添加高级 Chart.js 配置。

4. 典型生态项目

• Laravel: 提供基础框架。
• Chart.js: 用于渲染图表的 JavaScript 库。
• Node.js 和 npm：用于编译和打包前端资源。
• Laravel Mix 或 Vite：用于优化前端资源和提高开发效率。