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》组件）

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

LivewireLineChart 使用 LineChartModel 来设置数据点、标记、事件和其他UI自定义。
LivewirePieChart 使用 PieChartModel 来设置数据切片、事件和其他UI自定义。
LivewireColumnChart 使用 ColumnChartModel 来设置数据列、事件和其他UI自定义。
LivewireAreaChart 使用 AreaChartModel 来设置数据点、事件和其他UI自定义。
LivewireRadarChart 使用 RadarChartModel 来设置数据点、事件和其他UI自定义。
LivewireTreeMapChart 使用 TreeMapChartModel 来设置数据块、事件和其他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 指令

<livewire:scripts />
@livewireChartsScripts

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

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

LivewireCharts 门面

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

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

启用交互

要启用点击事件，您必须使用每个模型类中存在的 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组件中使用livewire-charts组件作为嵌套组件。一旦渲染，图表不会自动响应传递给$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

高级用法 - 集成脚本

指令@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

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全

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

致谢

许可协议

MIT许可协议（MIT）。有关更多信息，请参阅许可文件。

vigstudio / livewire-charts

维护者

详情