README

先决条件

Laravel 10 或更高版本
PHP 8.2 或更高版本
Highcharts，可在 window.Highcharts 中使用。
Livewire 2 或更高版本

安装

您可以通过 composer 安装此包

composer require bernskioldmedia/laravel-highcharts

安装包后，您需要导入用于显示图表的 Alpine JS 组件。您可以通过将以下内容添加到您的 resources/app.js 文件中来实现

import Chart from '../../vendor/bernskioldmedia/laravel-highcharts/resources/js/chart';

Alpine.data('highchartsChart', Chart); // Note that the Alpine component is expected to be named 'highchartsChart'.

如果您正在使用 Livewire 3，则需要根据 Livewire 文档手动打包 AlpineJS。然后，您的 resources/app.js 文件应如下所示

import {Livewire, Alpine} from '../../vendor/livewire/livewire/dist/livewire.esm';
import Chart from '../../vendor/bernskioldmedia/laravel-highcharts/resources/js/chart';

Alpine.data('highchartsChart', Chart); // Note that the Alpine component is expected to be named 'highchartsChart'.

Livewire.start();

发布配置和视图

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="laravel-highcharts-config"

这是已发布配置文件的内容

<?php

return [

    /**
     * Default options to be used for all charts.
     */
    'defaults' => [],

    /**
     * Default options to be used for all charts of a specific type.
     */
    'defaultsForType' => [
//        'line' => [
//            'title' => [
//                'text' => 'My Line Chart'
//            ]
//        ]
    ],

    /**
     * Defaults for chart labels.
     */
    'chartLabels' => [

        /**
         * CSS styles to be applied to the label.
         */
        'styles' => [
//            'fontWeight' => 'bold',
//            'fontSize' => '13px',
        ],

        /**
         * Additional Highchart drawing object attributes.
         */
        'attributes' => [
            'align' => 'center',
        ],
    ],

    /**
     * Defaults for chart lines.
     */
    'chartLines' => [

        /**
         * Highchart drawing object attributes.
         */
        'attributes' => [],
    ],

    /**
     * Defaults for chart quadrants.
     */
    'chartQuadrants' => [

        /**
         * Highchart drawing object attributes.
         */
        'attributes' => [],
    ],
];

可选地，您可以使用以下命令发布视图

php artisan vendor:publish --tag="laravel-highcharts-views"

用法

构建图表

该包提供了一系列方便的类，提供流畅的方法来添加数据和自定义基本 Highcharts 选项。这些类不是 Highcharts API 的完整实现，而是一种方便的方式，用于在 Laravel 应用程序中构建图表。

以下示例显示了如何构建一个简单的条形图

use BernskioldMedia\LaravelHighcharts\Data\DataPoint;
use BernskioldMedia\LaravelHighcharts\Data\Series;
use BernskioldMedia\LaravelHighcharts\Data\Chart;

$chart = Chart::make('test-chart')
    ->title('Example Bar Chart')
    ->bar()
    ->series([
        Series::make([
            DataPoint::make(
                x: '2021-01-01',
                y: 10
            ),
            DataPoint::make(
                x: '2022-01-01',
                y: 20
            ),
            DataPoint::make(
                x: '2023-01-01',
                y: 30
            )
        ])    
    ]);

由于我们不打算为所有 Highcharts 选项添加流畅的方法，您可以使用 set 和 setMany 方法添加任何需要的选项。选项嵌套和键与 Highcharts API 中的相同。键支持点符号进行嵌套。

例如，要禁用动画，您可以这样做

$chart = Chart::make('test-chart')
    ->title('Example Bar Chart')
    ->bar()
    ->set('chart.animation', false)
    ->setMany();

在 Livewire 组件中渲染图表

此包支持每个 Livewire 组件一个图表。要渲染图表，涉及三个步骤

使用 Data\Chart 类（见下文）构建包含数据的图表
在您的 Livewire 组件中实现 InteractsWithChart 特性。
在 Livewire 组件的视图中渲染 Blade 组件。

您的 Livewire 组件可能如下所示

<?php

namespace App\Livewire;

use BernskioldMedia\LaravelHighcharts\Concerns\Livewire\InteractsWithCharts;
use BernskioldMedia\LaravelHighcharts\Data\DataPoint;
use BernskioldMedia\LaravelHighcharts\Data\Series;
use Livewire\Component;

class MyChartComponent extends Component
{
    use InteractsWithChart;
    
    protected function getChart(): Chart
    {
        return Chart::make('test-chart')
            ->title('Example Bar Chart')
            ->bar()
            ->series([
                Series::make([
                    DataPoint::make(
                        x: '2021-01-01',
                        y: 10
                    ),
                    DataPoint::make(
                        x: '2022-01-01',
                        y: 20
                    ),
                    DataPoint::make(
                        x: '2023-01-01',
                        y: 30
                    )
                ])    
            ]);
    }

    public function render()
    {
        return view('livewire.my-chart-component');
    }
}

您的 Livewire 组件的 Blade 部分可能如下所示

<div>
    <x-highcharts::chart chart-key="test-chart" />
</div>

注意： chart-key 属性是必需的，并且必须与构建图表时使用的键匹配。

使用 "Chart Extras" 绘制图表

该包提供了一种使用 "Chart Extras" 在图表上绘制的方式。这些类创建了一个流畅的界面，用于在图表上绘制常见的非数据元素所需的数据：象限、线和标签。

绘制象限

以下示例在图表上从原点到点 (10, 10) 绘制一个黑色象限

use BernskioldMedia\LaravelHighcharts\Data\Chart;
use BernskioldMedia\LaravelHighcharts\Data\ChartExtras;
use BernskioldMedia\LaravelHighcharts\Data\ChartQuadrant;

$chart = Chart::make('test-chart')
    ->bar()
    ->extras(function(ChartExtras $extras) {
        $extras->addQuadrant(
            ChartQuadrant::make()
            ->from(0, 0)
            ->to(10, 10)
            ->attributes([
                'fill' => '#000000',
            ])
        );
    });

绘制线

以下示例在图表上从原点到点 (100, 100) 绘制一条黑色线

use BernskioldMedia\LaravelHighcharts\Data\Chart;
use BernskioldMedia\LaravelHighcharts\Data\ChartExtras;
use BernskioldMedia\LaravelHighcharts\Data\ChartLine;

$chart = Chart::make('test-chart')
    ->bar()
    ->extras(function(ChartExtras $extras) {
        $extras->addLine(
            ChartLine::make()
            ->from(0, 0)
            ->to(10, 10)
            ->attributes([
                'stroke' => '#000000',
            ])
        );
    });

添加标签

以下示例在图表的点 (75, 75) 添加一个黑色、居中的标签

use BernskioldMedia\LaravelHighcharts\Data\Chart;
use BernskioldMedia\LaravelHighcharts\Data\ChartExtras;
use BernskioldMedia\LaravelHighcharts\Data\ChartLabel;

$chart = Chart::make('test-chart')
    ->bar()
    ->extras(function(ChartExtras $extras) {
        $extras->addLabel(
            ChartLabel::make()
                ->coordinates(75, 75)
                ->styles([
                    'color' => '#000000',
                ])
                ->attributes([
                    'align' => 'center',
                ])
        );
    });

导出图表

每个图表都会监听 window 对象上的 export-chart 事件。通过触发此事件并使用适当的详细信息，可以从 JavaScript 或 Livewire 中导出任何图表。

详细对象必须包含 chartId 和 type 键。必须与构建图表时使用的键匹配 chartId。必须是对 Highcharts exportChartLocal 方法有效的 type。

exportSettings 可以接收一个对象，其中包含根据 Highcharts 的 exportChartLocal 方法设置的导出选项。options 接收一个对象，其中包含图表选项，用于在导出之前自定义图表。

以下示例展示了如何从 JavaScript 中导出图表

window.dispatchEvent(new CustomEvent('export-chart', {
    detail: {
        chartId: 'test-chart',
        type: 'image/png',
        exportSettings: {}, // Optional.
        options: {}, // Optional.
    }
}));

使用 Livewire，您可以使用 dispatch 方法，或者使用捆绑的 ExportsChart 特性。

// Using the trait.
use BernskioldMedia\LaravelHighcharts\Concerns\Livewire\ExportsChart;

$this->exportChart(
    type: 'image/png',
    chartKey: 'test-chart',
    exportSettings: [], // Optional.
    options: [], // Optional.
);

// Using Livewire 3's dispatch method.
$this->dispatch(
    'exportChart',
    chartId: 'test-chart',
    type: 'image/png',
    exportSettings: [], // Optional.
    options: [], // Optional.
);

如果您正在使用 ExportsChart 特性，您还可以通过向 Livewire 组件中添加 getChartExportSettings 和 getChartOptionsForExport 方法来自定义导出设置和选项。为确保它们的签名，我们建议实现捆绑的 CustomizesChartExportOptions 和 CustomizesChartExportSettings 接口。

如果您在具有 InteractsWithChart 特性的同一组件上使用特性，则无需提供图表键，可以使用最简语法

use BernskioldMedia\LaravelHighcharts\Concerns\Livewire\ExportsChart;

$this->exportChart('image/png');

测试

composer test

bernskioldmedia / laravel-highcharts

维护者

详细信息