Symfony UX Chart.js

編輯此頁

Symfony UX Chart.js 是一個 Symfony 套件，整合了 Symfony 應用程式中的 Chart.js 程式庫。它是 Symfony UX 計畫 的一部分。

安裝

使用 Composer 和 Symfony Flex 安裝套件

1
$ composer require symfony/ux-chartjs

如果您使用 WebpackEncore，請安裝您的資源並重新啟動 Encore (如果您使用 AssetMapper 則不需要)

1
2
$ npm install --force
$ npm run watch

用法

若要使用 Symfony UX Chart.js，請注入 ChartBuilderInterface 服務，並在 PHP 中建立圖表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// ...
use Symfony\UX\Chartjs\Builder\ChartBuilderInterface;
use Symfony\UX\Chartjs\Model\Chart;

class HomeController extends AbstractController
{
    #[Route('/', name: 'app_homepage')]
    public function index(ChartBuilderInterface $chartBuilder): Response
    {
        $chart = $chartBuilder->createChart(Chart::TYPE_LINE);

        $chart->setData([
            'labels' => ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
            'datasets' => [
                [
                    'label' => 'My First dataset',
                    'backgroundColor' => 'rgb(255, 99, 132)',
                    'borderColor' => 'rgb(255, 99, 132)',
                    'data' => [0, 10, 5, 2, 20, 30, 45],
                ],
            ],
        ]);

        $chart->setOptions([
            'scales' => [
                'y' => [
                    'suggestedMin' => 0,
                    'suggestedMax' => 100,
                ],
            ],
        ]);

        return $this->render('home/index.html.twig', [
            'chart' => $chart,
        ]);
    }
}

所有選項和資料都按原樣提供給 Chart.js。您可以閱讀 Chart.js 文件 以探索所有選項和資料。

在 PHP 中建立圖表後，可以使用 Twig 顯示圖表

1
2
3
4
{{ render_chart(chart) }}

{# You can pass HTML attributes as a second argument to add them on the <canvas> tag #}
{{ render_chart(chart, {'class': 'my-chart'}) }}

使用外掛程式

Chart.js 隨附 許多外掛程式，可擴充其預設行為。讓我們看看如何使用 zoom 外掛程式，方法是依照 zoom 外掛程式文件 進行操作。

首先，安裝外掛程式

1
$ npm install chartjs-plugin-zoom -D

然後全域註冊外掛程式。這可以在您的 app.js 檔案中完成

1
2
3
4
5
6
7
8
9
10
// assets/app.js
import zoomPlugin from 'chartjs-plugin-zoom';

// register globally for all charts
document.addEventListener('chartjs:init', function (event) {
    const Chart = event.detail.Chart;
    Chart.register(zoomPlugin);
});

// ...

最後，使用圖表選項設定外掛程式。例如，zoom 外掛程式文件顯示以下範例設定

1
2
3
4
5
6
7
8
9
10
11
12
13
// ...
options: {
    plugins: {
        zoom: {
            zoom: {
              wheel: { enabled: true },
              pinch: { enabled: true },
              mode: 'xy',
            }
        }
    }
}
// ...

若要在 Symfony UX Chart.js 中使用相同的設定，您可以使用 setOptions() 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$chart = $chartBuilder->createChart(Chart::TYPE_LINE);

// ...

$chart->setOptions([
    'plugins' => [
        'zoom' => [
            'zoom' => [
                'wheel' => ['enabled' => true],
                'pinch' => ['enabled' => true],
                'mode' => 'xy',
            ],
        ],
    ],
]);

擴充預設行為

Symfony UX Chart.js 可讓您使用自訂 Stimulus 控制器擴充其預設行為

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
// mychart_controller.js

import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
    connect() {
        this.element.addEventListener('chartjs:pre-connect', this._onPreConnect);
        this.element.addEventListener('chartjs:connect', this._onConnect);
    }

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side effects
        this.element.removeEventListener('chartjs:pre-connect', this._onPreConnect);
        this.element.removeEventListener('chartjs:connect', this._onConnect);
    }

    _onPreConnect(event) {
        // The chart is not yet created
        // You can access the config that will be passed to "new Chart()"
        console.log(event.detail.config);

        // For instance you can format Y axis
        // To avoid overriding existing config, you should distinguish 3 cases:
        // # 1. No existing scales config => add a new scales config
        event.detail.config.options.scales = {
            y: {
                ticks: {
                    callback: function (value, index, values) {
                        /* ... */
                    },
                },
            },
        };
        // # 2. Existing scales config without Y axis config => add new Y axis config
        event.detail.config.options.scales.y = {
            ticks: {
                callback: function (value, index, values) {
                    /* ... */
                },
            },
        };
        // # 3. Existing Y axis config => update it
        event.detail.config.options.scales.y.ticks = {
            callback: function (value, index, values) {
                /* ... */
            },
        };
    }

    _onConnect(event) {
        // The chart was just created
        console.log(event.detail.chart); // You can access the chart instance using the event details

        // For instance you can listen to additional events
        event.detail.chart.options.onHover = (mouseEvent) => {
            /* ... */
        };
        event.detail.chart.options.onClick = (mouseEvent) => {
            /* ... */
        };
    }
}

然後在您的 render 呼叫中，將您的控制器新增為 HTML 屬性

1
{{ render_chart(chart, {'data-controller': 'mychart'}) }}

還有一個 chartjs:init 事件，它只在您的第一個圖表呈現之前呼叫 *一次*。這是全域註冊 Chart.js 外掛程式或對 Chart.js 的任何「靜態」/全域部分進行其他變更的理想位置。例如，新增全域 Tooltip 定位器

1
2
3
4
5
6
7
8
9
10
// assets/app.js

// register globally for all charts
document.addEventListener('chartjs:init', function (event) {
    const Chart = event.detail.Chart;
    const Tooltip = Chart.registry.plugins.get('tooltip');
    Tooltip.positioners.bottom = function(items) {
        /* ... */
    };
});

向後相容性承諾

此套件旨在遵循與 Symfony 框架相同的向後相容性承諾：https://symfony.dev.org.tw/doc/current/contributing/code/bc.html。

這項作品，包括程式碼範例，已根據 Creative Commons BY-SA 3.0 授權條款授權。
目錄
    版本