README

一个简单的包，用于简化并自动化在Laravel中使用Chart.js库创建图表的过程。

设置

此包提供了一个Chart.js的包装器，允许您在Laravel应用程序中简单方便地使用它。根据您的需求和JavaScript熟悉程度，该包支持多种安装方法。

1. 安装此包

composer require icehouse-ventures/laravel-chartjs

对于Laravel的旧版本（8及以下），请在您的文件config/app.php中添加服务提供者

IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider::class

将配置文件发布到您自己的应用程序将允许您通过设置Chart.js版本和Chart.js文件的交付方式等来自定义包。

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

2. 安装Chartjs

接下来，您可以在您的布局/模板中安装并添加Chart.js库，该库可以轻松地从以下链接下载：https://chart.js.cn

Chartjs有几种安装选项。默认情况下，此包设置为使用'自定义'自管理交付方法（以避免与现有安装冲突）。您还可以选择其他几种交付方法

CDN

对于快速开发和测试不同版本，您可以在config\chartjs.php设置中将交付方法轻松设置为'CDN'，这将通过外部内容交付网络加载指定的Chartjs文件。CDN提供2、3和4版本的Chartjs。这些版本还加载Moment.js和Numeral.js，这些通常是业务图表所必需的。

发布

如果您在应用程序的任何其他地方都没有使用JavaScript包或者您是JavaScript开发的初学者，那么您可能还没有设置Node Package Manager、Laravel Mix或Vite。在这种情况下，此包包括可用于您的应用程序的预编译版本的Chartjs。要发布chart.js二进制文件到您应用程序的公共文件夹（JavaScript包存储的地方），您可以发布包的预构建的分布资产。

默认情况下，发布方法将使用包中的最新二进制文件安装4版本的Chartjs。如果您想发布较旧版本，我们还提供了3和2版本的最新稳定版Chartjs。您可以使用以下命令将这些发布到您的公共资产文件夹

// Publish Chartjs version 4 assets
php artisan vendor:publish --provider="IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider" --force --tag="assets"

// Publish Chartjs version 3 assets 
php artisan vendor:publish --provider="IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider" --force --tag="assets-v3"

// Publish Chartjs version 2 assets 
php artisan vendor:publish --provider="IcehouseVentures\LaravelChartjs\Providers\ChartjsServiceProvider" --force --tag="assets-v2"

二进制文件

在某些罕见情况下，例如在没有互联网连接的本地开发、私有应用程序、共享服务器或您无法访问服务器上的公共文件夹时，您可能希望最终用户直接加载二进制文件。这种方法不建议使用，因为它从您的应用程序内部流式传输文件的文件内容。此交付方法将从您的供应商文件夹中直接加载通常发布到您的资产文件夹的Chartjs文件。要使用此方法，将交付配置变量设置为'binary'并在配置文件中选择您希望使用的Chartjs版本。

NPM（推荐）

在Web应用程序中安装Chartjs的推荐方法是将其包含在您的常规JavaScript和/或CSS包管道中，使用NPM、Laravel Mix或Vite。有关此安装方法的说明，请访问：https://chart.js.cn/docs/latest/getting-started/

用法

您可以请求服务容器中负责构建图表并通过流畅的接口传递图表设置的图表服务。

use IcehouseVentures\LaravelChartjs\Facades\Chartjs;

$chart = Chartjs::build()
    ->name()
    ->type()
    ->size()
    ->labels()
    ->datasets()
    ->options();

构建器需要图表的名称、可以是被 Chartjs 支持的任何类型的图表以及其他自定义配置，如标签、数据集、大小和选项。

在数据集接口中，您可以传递任何配置和选项到您的图表。所有在 Chartjs 文档中可用的选项都受支持。只需使用 PHP 数组表示法编写配置即可！

$chart->options([
        'scales' => [
            'x' => [
                'title' => [
                    'display' => true,
                    'text' => 'X Axis Title'
                ],
            ]
        ]
    ]);

高级 Chartjs 选项

基本的 options() 方法允许您添加基于简单键值对的选项。使用 optionsRaw() 方法，可以以原始 JSON 格式添加更复杂的嵌套 Chartjs 选项，并调用插件的选项。

传递字符串格式如 JSON

$chart->optionsRaw("{
        scales: {
            x: {
                title: {
                    display: true,
                    text: 'X Axis Title',
                }
            }
        },
        plugins: {
            title: {
                display: true,
                text: 'Chart Title',
                font: {
                    size: 16
                }
            },
            legend: {
                display: false,
            },
        }
    }");

示例

1 - 折线图

// Controller CExampleController.php
use IcehouseVentures\LaravelChartjs\Facades\Chartjs;

$chart = Chartjs::build()
        ->name('lineChartTest')
        ->type('line')
        ->size(['width' => 400, 'height' => 200])
        ->labels(['January', 'February', 'March', 'April', 'May', 'June', 'July'])
        ->datasets([
            [
                "label" => "My First dataset",
                'backgroundColor' => "rgba(38, 185, 154, 0.31)",
                'borderColor' => "rgba(38, 185, 154, 0.7)",
                "pointBorderColor" => "rgba(38, 185, 154, 0.7)",
                "pointBackgroundColor" => "rgba(38, 185, 154, 0.7)",
                "pointHoverBackgroundColor" => "#fff",
                "pointHoverBorderColor" => "rgba(220,220,220,1)",
                "data" => [65, 59, 80, 81, 56, 55, 40],
                "fill" => false,
            ],
            [
                "label" => "My Second dataset",
                'backgroundColor' => "rgba(38, 185, 154, 0.31)",
                'borderColor' => "rgba(38, 185, 154, 0.7)",
                "pointBorderColor" => "rgba(38, 185, 154, 0.7)",
                "pointBackgroundColor" => "rgba(38, 185, 154, 0.7)",
                "pointHoverBackgroundColor" => "#fff",
                "pointHoverBorderColor" => "rgba(220,220,220,1)",
                "data" => [12, 33, 44, 44, 55, 23, 40],
                "fill" => false,
            ]
        ])
        ->options([]);

return view('example', compact('chart'));

// Blade example.blade.php

<div style="width:75%;">
    <x-chartjs-component :chart="$chart" />
</div>

2 - 柱状图

// Controller ExampleController.php
use IcehouseVentures\LaravelChartjs\Facades\Chartjs;

$chart = Chartjs::build()
         ->name('barChartTest')
         ->type('bar')
         ->size(['width' => 400, 'height' => 200])
         ->labels(['Label x', 'Label y'])
         ->datasets([
             [
                 "label" => "My First dataset",
                 'backgroundColor' => ['rgba(255, 99, 132, 0.2)', 'rgba(54, 162, 235, 0.2)'],
                 'data' => [69, 59]
             ],
             [
                 "label" => "My First dataset",
                 'backgroundColor' => ['rgba(255, 99, 132, 0.3)', 'rgba(54, 162, 235, 0.3)'],
                 'data' => [65, 12]
             ]
         ])
         ->options([
            "scales" => [
                "y" => [
                    "beginAtZero" => true
                    ]
                ]
         ]);

return view('example', compact('chart'));

// Blade example.blade.php

<div style="width:75%;">
    <x-chartjs-component :chart="$chart" />
</div>

3 - 饼图/甜甜圈图

// Controller ExampleController.php
use IcehouseVentures\LaravelChartjs\Facades\Chartjs;

$chart = Chartjs::build()
        ->name('pieChartTest')
        ->type('pie')
        ->size(['width' => 400, 'height' => 200])
        ->labels(['Label x', 'Label y'])
        ->datasets([
            [
                'backgroundColor' => ['#FF6384', '#36A2EB'],
                'hoverBackgroundColor' => ['#FF6384', '#36A2EB'],
                'data' => [69, 59]
            ]
        ])
        ->options([]);

return view('example', compact('chart'));

// Blade example.blade.php

<div style="width:75%;">
    <x-chartjs-component :chart="$chart" />
</div>

高级自定义视图

如果您需要编辑底层的 Blade 组件（以调整 CDN 逻辑或对用于渲染图表的 <canvas> 元素进行更深入的 CSS 更改），您可以发布视图。

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

然后您可以在应用程序中的 ./views/vendor/laravelchartjs/chart-template.blade.php 文件中自定义已发布的 Blade 文件。

要撤销任何自定义，只需从应用程序中删除或重命名此文件即可。

Livewire 支持

此包对 Livewire 的实时更新具有原型支持。请参阅演示仓库

 // Inside your Livewire blade component: example-livewire-chart-demo.blade.php
<div class="main">

    <div class="chart-container">
        <x-chartjs-component :chart="$chart" />
    </div>

</div>

// Inside your  Livewire php component: ExampleLivewireChartDemo.php
use IcehouseVentures\LaravelChartjs\Facades\Chartjs;

class ExampleLivewireChartDemo extends Component
{
    public $datasets;

    #[Computed]
    public function chart()
    {
        return Chartjs::build()
            ->name("UserRegistrationsChart")
            ->livewire()
            ->model("datasets")
            ->type("line");
    }

    public function render()
    {
        $this->getData();

        return view('livewire.example-livewire-chart-demo');
    }
    
    public function getData()
    {
        $data = []; // your data here
        $labels = []; // your labels here
        
        $this->datasets = [
            'datasets' => [
                [
                    "label" => "User Registrations",
                    "backgroundColor" => "rgba(38, 185, 154, 0.31)",
                    "borderColor" => "rgba(38, 185, 154, 0.7)",
                    "data" => $data
                ]
            ],
            'labels' => $labels
        ]
    }
}

遗留支持

此包还支持旧版本的 Laravel 和 Chartjs。构建图表的先前语法仍然受支持，可以通过 app()->chartjs 方法访问。之前的 blade 渲染语法也仍然受支持，可以通过 {{ app()->chartjs()->render() }} 指令访问。遗留语法对于从先前版本迁移到此包特别有用。

// Controller ExampleController.php

$chartjs = app()->chartjs
        ->name('pieChartTest')
        ->type('pie')
        ->size(['width' => 400, 'height' => 200])
        ->labels(['Label x', 'Label y'])
        ->datasets([
            [
                'backgroundColor' => ['#FF6384', '#36A2EB'],
                'hoverBackgroundColor' => ['#FF6384', '#36A2EB'],
                'data' => [69, 59]
            ]
        ])
        ->options([]);

return view('example', compact('chartjs'));

// Blade example.blade.php

<div style="width:75%;">
    {!! $chartjs->render() !!}
</div>

问题

此 README 以及该包正在开发中，但将持续更新，我们将保持您的知情权。如有任何问题或建议，请先开启讨论，然后再创建问题。

许可证

LaravelChartjs 是开源软件，受 MIT 许可证许可。

来源

此包的一些原始逻辑最初是由 Brian Faust 开发的。此版本的包主要是由 Felix Costa 开发和维护的。到 2024 年，该包被新西兰的一家早期风险投资公司 Icehouse Ventures 采用。我们在 Laravel 应用程序中大量使用 Chartjs，并希望通过使 Chartjs 在所有主要版本中快速且易于实现以及简化升级路径来回馈 Laravel 社区。

icehouse-ventures / laravel-chartjs

维护者

详细信息