README

预览

演示

https://github.com/asantibanez/livewire-charts-demo

安装

您可以通过composer安装此包

composer require asantibanez/livewire-charts

接下来，您必须导出包的公共脚本。为此，请运行

php artisan livewire-charts:install

此命令将在您的应用public目录下导出vendor/livewire-charts文件夹，该文件夹由@livewireChartsScripts指令使用。关于这个话题的更多内容将在后面介绍。

需求

此包需要以下包/库才能工作

Laravel Livewire v3 (https://livewire.laravel.net.cn/)
Apex Charts (https://apexcharts.com/)

请按照每个包/库的说明，在项目中正确设置它们。

注意：目前，仅支持Apex Charts用于绘制图表。

用法

Livewire Charts支持以下类型的图表

线/多线图表（LivewireLineChart组件）
饼图（LivewirePieChart组件）
柱/多线图表（LivewireColumnChart组件）
面积图（LivewireAreaChart组件）
雷达图（LivewireRadarChart组件）
树状图（LivewireTreeMapChart组件）
径向图（LivewireRadialChart组件）

每个图表都附带一个自己的“模型”类，允许您定义图表的数据和渲染行为。

LivewireLineChart使用LineChartModel来设置数据点、标记、事件和其他UI自定义。
LivewirePieChart使用PieChartModel来设置数据切片、事件和其他UI自定义。
LivewireColumnChart使用ColumnChartModel来设置数据列、事件和其他UI自定义。
LivewireAreaChart使用AreaChartModel来设置数据点、事件和其他UI自定义。
LivewireRadarChart使用RadarChartModel来设置数据点、事件和其他UI自定义。
LivewireTreeMapChart使用TreeMapChartModel来设置数据块、事件和其他UI自定义。
LivewireRadialChart使用RadialChartModel来设置数据条、事件和其他UI自定义。

例如，要渲染柱状图，我们可以创建一个ColumnChartModel实例并向其中添加一些数据

$columnChartModel = 
    (new ColumnChartModel())
        ->setTitle('Expenses by Type')
        ->addColumn('Food', 100, '#f6ad55')
        ->addColumn('Shopping', 200, '#fc8181')
        ->addColumn('Travel', 300, '#90cdf4')
    ;

注意：图表模型方法是可以链式的 💪

有了$columnChartModel，我们将其传递到我们的Blade模板中的LivewireColumnChart组件中。

<livewire:livewire-column-chart
    {{-- key="{{ $columnChartModel->reactiveKey() }}" --}}
    :column-chart-model="$columnChartModel"
/>

注意：可选地添加“key”以启用属性反应，如果需要的话 💪

接下来，在您的其他应用脚本旁边包含@livewireChartsScripts指令

@livewireScripts
@livewireChartsScripts

就这样！您在几秒钟内就有一个美丽的渲染图表。👌

注意：您也可以在其他Livewire组件中使用这些图表。只需在Blade模板中渲染它们即可。👍

LivewireCharts门面

您也可以使用LivewireCharts门面创建图表模型。

LivewireCharts::lineChartModel();
LivewireCharts::multiLineChartModel();
LivewireCharts::columnChartModel();
LivewireCharts::multiColumnChartModel();
LivewireCharts::pieChartModel();
LivewireCharts::areaChartModel();
LivewireCharts::radarChartModel();
LivewireCharts::treeMapChartModel();
LivewireCharts::radialChartModel();

启用交互

要启用点击事件，您必须使用每个模型类中存在的with[XXX]ClickEvent($eventName)方法，并定义一个当点击柱/标记/切片时将触发对应数据的自定义$eventName。

$columnChartModel = 
    (new ColumnChartModel())
        ->setTitle('Expenses by Type')
        ->withOnColumnClickEventName('onColumnClick')
    ;

在这里，我们定义了一个onColumnClick事件，当在图表中点击柱子时将触发。

我们可以在任何其他Livewire组件中监听onClickEvent，注册一个监听器。

#[On('onColumnClick')]
public function handleOnColumnClick($event)
{
   // Handle event
}

“反应式”图表

您可以将 livewire-charts 组件用作 Livewire 组件的嵌套组件。一旦渲染，图表将不会自动对传入的 $model 的变化做出反应。这正是 Livewire 的工作方式。

然而，为了使数据传入变化时启用“反应性”，您可以在组件中定义一个特殊的 $key，这样每次图表数据变化时，它们都会完全重新渲染。

每个模型类都包含一个 reactiveKey() 方法，该方法根据其数据返回一个字符串。如果任何属性发生变化，此键将相应更新并重新渲染图表。

以下示例中，父组件包含柱状图和饼图，并为每个定义了一个 $model。父组件按以下方式渲染图表

<livewire:livewire-column-chart
    key="{{ $columnChartModel->reactiveKey() }}"
    :column-chart-model="$columnChartModel"
/>

<livewire:livewire-pie-chart
    key="{{ $pieChartModel->reactiveKey() }}"
    :pie-chart-model="$pieChartModel"
/>

当父组件更改各自的模型时，图表将自动重新渲染。

图表 API

对于每个图表，都需要使用特定的模型类。在此，详细介绍了每种图表类型可用的 API。

所有

LivewireLineChart

LivewireColumnChart

LivewirePieChart

LivewireAreaChart

LivewireRadarChart

LivewireTreeMapChart

LivewireRadialChart

高级使用 - 集成脚本

指令 @livewireChartsScripts 添加了一个包含 public/vendor/livewire-charts/app.js 的 script 标签。如果您想将其包含在构建系统中，可以使用 php artisan vendor:publish 并选择 livewire-charts:scripts 来导出包脚本。这将导出 js/vendor/livewire-charts 到您的资源文件夹中。您可以在项目中根据需要调整导入。

注意：您必须删除 @livewireChartsScripts 指令，以避免与构建系统中的脚本冲突。

高级使用 - 自定义 Json 配置

每个图表上的 setJsonConfig() 方法允许添加 Apex 包含的属性。这意味着可以使用此方法传递任何 Apex 支持的图表属性。

$chart->setJsonConfig([
    'plotOptions.pie.startAngle' => -90,
    'plotOptions.pie.endAngle' => 90,
    'plotOptions.pie.offsetY' => 10,
    'grid.padding.bottom' => -180,
]);

注意：如果您想添加嵌套属性，可以使用点（.）符号。

您甚至可以传递简单的 JS 函数。例如，对于格式化，您可以传递自己的闭包

$chart->setJsonConfig([
    'tooltip.y.formatter' => '(val) => `$${val} million dollars baby!`'
])

故障排除

图表组件必须放置在具有固定高度的容器内。这是因为图表将使用所有给定的垂直空间。需要固定高度才能正确渲染。

<div style="height: 32rem;">
   <livewire:livewire-column-chart .../>
</div>

注意：如果没有给定固定高度，图表将垂直无限增长。这不是我们想要的，对吧？

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近更改的信息。

贡献

请参阅 CONTRIBUTING 了解详情。

安全

如果您发现任何与安全相关的问题，请通过电子邮件 santibanez.andres@gmail.com 而不是使用问题跟踪器。

致谢

许可证

MIT 许可证 (MIT)。请参阅许可证文件了解更多信息。

asantibanez / livewire-charts

维护者

详细信息