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-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

高级使用 - 集成脚本

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

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

高级使用 - 自定义JSON配置

每个图表上的setJsonConfig()方法允许添加由包直接提供的Apex属性之外的自定义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）。有关更多信息，请参阅许可证文件。

flakron / livewire-charts

维护者

详细信息