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 图表支持的任何图表属性。

$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）。有关更多信息，请参阅许可文件。

matheuslessing / livecharts

维护者

详细信息