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

变更日志

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

贡献

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

安全性

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

鸣谢

许可证

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

arukompas / livewire-charts

维护者

详细信息