数据统计卡片

Dcat Admin中内置了多种常用数据统计卡片,可以非常方便的与后端API交互,下面逐一介绍用法。

基础卡片

基础卡片(Dcat\Admin\Widgets\Metrics\Card)是一种默认不显示图表的卡片,也是数据卡片中最简单的一种。

数据统计卡片 - 图1

简单示例

基础卡片的使用可参考内置的App\Admin\Metrics\Examples\TotalUsers类。

  1. <?php
  2. namespace App\Admin\Metrics\Examples;
  3. use Dcat\Admin\Widgets\Metrics\Card;
  4. use Illuminate\Contracts\Support\Renderable;
  5. use Illuminate\Http\Request;
  6. class TotalUsers extends Card
  7. {
  8. /**
  9. * 卡片底部内容.
  10. *
  11. * @var string|Renderable|\Closure
  12. */
  13. protected $footer;
  14. // 保存自定义参数
  15. protected $data = [];
  16. // 构造方法参数必须设置默认值
  17. public function __construct(array $data = [])
  18. {
  19. $this->data = [];
  20. parent::__construct();
  21. }
  22. protected function init()
  23. {
  24. parent::init();
  25. // 设置标题
  26. $this->title('Total Users');
  27. // 设置下拉菜单
  28. $this->dropdown([
  29. '7' => 'Last 7 Days',
  30. '28' => 'Last 28 Days',
  31. '30' => 'Last Month',
  32. '365' => 'Last Year',
  33. ]);
  34. }
  35. /**
  36. * 处理请求.
  37. *
  38. * @param Request $request
  39. *
  40. * @return void
  41. */
  42. public function handle(Request $request)
  43. {
  44. // 获取外部传递的自定义参数
  45. $key1 = $request->get('key1');
  46. switch ($request->get('option')) {
  47. case '365':
  48. $this->content(mt_rand(600, 1500));
  49. $this->down(mt_rand(1, 30));
  50. break;
  51. case '30':
  52. $this->content(mt_rand(170, 250));
  53. $this->up(mt_rand(12, 50));
  54. break;
  55. case '28':
  56. $this->content(mt_rand(155, 200));
  57. $this->up(mt_rand(5, 50));
  58. break;
  59. case '7':
  60. default:
  61. $this->content(143);
  62. $this->up(15);
  63. }
  64. }
  65. // 传递自定义参数到 handle 方法
  66. public function parameters() : array
  67. {
  68. return $this->data;
  69. }
  70. /**
  71. * @param int $percent
  72. *
  73. * @return $this
  74. */
  75. public function up($percent)
  76. {
  77. return $this->footer(
  78. "<i class=\"feather icon-trending-up text-success\"></i> {$percent}% Increase"
  79. );
  80. }
  81. /**
  82. * @param int $percent
  83. *
  84. * @return $this
  85. */
  86. public function down($percent)
  87. {
  88. return $this->footer(
  89. "<i class=\"feather icon-trending-down text-danger\"></i> {$percent}% Decrease"
  90. );
  91. }
  92. /**
  93. * 设置卡片底部内容
  94. *
  95. * @param string|Renderable|\Closure $footer
  96. *
  97. * @return $this
  98. */
  99. public function footer($footer)
  100. {
  101. $this->footer = $footer;
  102. return $this;
  103. }
  104. /**
  105. * 渲染卡片内容.
  106. *
  107. * @return string
  108. */
  109. public function renderContent()
  110. {
  111. $content = parent::renderContent();
  112. return <<<HTML
  113. <div class="d-flex justify-content-between align-items-center mt-1" style="margin-bottom: 2px">
  114. <h2 class="ml-1 font-large-1">{$content}</h2>
  115. </div>
  116. <div class="ml-1 mt-1 font-weight-bold text-80">
  117. {$this->renderFooter()}
  118. </div>
  119. HTML;
  120. }
  121. /**
  122. * @return string
  123. */
  124. public function renderFooter()
  125. {
  126. return $this->toString($this->footer);
  127. }
  128. }

基础卡片方法

初始化 (init)

init方法会在卡片构造方法中被调用,可用于卡片初始化操作。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. // 你的初始化操作
  7. }
  8. }

设置标题 (title)

通过title方法可以在卡片的左上角设置一个标题

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->title('活跃用户');
  7. }
  8. }

设置下拉菜单 (dropdown)

通过dropdown方法可以在卡片右上角设置一个下拉菜单按钮,此功能需要结合handle方法一起使用才有效果。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. $this->dropdown([
  6. '7' => 'Last 7 Days',
  7. '28' => 'Last 28 Days',
  8. '30' => 'Last Month',
  9. '365' => 'Last Year',
  10. ]);
  11. }
  12. }

设置副标题 (subTitle)

通过subTitle方法可以在卡片的又上角设置一个副标题。

{tip} 此方法与dropdown方法会有冲突,如果设置过下拉菜单按钮,就不需要设置副标题。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->subTitle('最近30天');
  7. }
  8. }

设置头部内容 (header)

通过header方法可以设置卡片头部内容,此方法接受一个参数,可以是stringClosure,也可以是模板视图(Illuminate\Contracts\Support\Renderable)。

{tip} 通过此方法设置的内容与title在同一个div容器内。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->header(
  7. <<<HTML
  8. <div>头部内容</div>
  9. HTML
  10. );
  11. // 也可以传闭包
  12. $this->header(function () {
  13. return ...;
  14. });
  15. // 也可以传视图
  16. $this->header(view('...'));
  17. }
  18. }

设置主体内容 (content)

通过content方法可以设置卡片的内容主体,此方法接受一个参数,可以是stringClosure,也可以是模板视图(Illuminate\Contracts\Support\Renderable)。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->withContent('自定义内容');
  7. }
  8. /**
  9. * 卡片内容
  10. *
  11. * @param string $content
  12. *
  13. * @return $this
  14. */
  15. public function withContent($content)
  16. {
  17. return $this->content(
  18. <<<HTML
  19. <div class="d-flex flex-column flex-wrap text-center">
  20. <h1 class="font-large-2 mt-2 mb-0">{$content}</h1>
  21. <small>Tickets</small>
  22. </div>
  23. HTML
  24. );
  25. }
  26. }

设置高度 (height)

通过height方法可以设置卡片的最小高度,默认165

  1. protected function init()
  2. {
  3. parent::init();
  4. $this->height(200);
  5. }

传递自定义参数 (parameters)

通过 parameters 方法可以把参数传递到 handle 方法

  1. // 传递自定义参数到 handle 方法
  2. public function parameters() : array
  3. {
  4. return [
  5. 'key1' => 'value1',
  6. ...
  7. ];
  8. }

获取自定义参数

  1. public function handle(Request $request)
  2. {
  3. // 获取自定义参数
  4. $key1 = $request->get('key1');
  5. }

渲染内容 (renderContent)

为了保证内容的灵活和可扩展性,系统没有对卡片内容预设任何样式(即设置什么内容就只显示什么内容,没有预设布局或其他样式), 通过renderContent方法即可以更改卡片默认的渲染方式。

以下的例子演示了renderContent方法的主要功能

  1. use Dcat\Admin\Support\Helper;
  2. class MyCard extend Card
  3. {
  4. protected $footer;
  5. protected function init()
  6. {
  7. parent::init();
  8. // 设置卡片内容
  9. $this->content(...);
  10. // 设置卡片底部内容
  11. $this->footer(...);
  12. }
  13. /**
  14. * 增加此方法设置卡片底部内容
  15. *
  16. * @return $this
  17. */
  18. public function footer($footer)
  19. {
  20. $this->footer = $footer;
  21. return $this;
  22. }
  23. /**
  24. * 渲染底部内容
  25. *
  26. * @return $this
  27. */
  28. public function renderFooter()
  29. {
  30. return Helper::render($this->footer);
  31. }
  32. /**
  33. * 渲染卡片内容
  34. * 在这里即可加上卡片底部内容
  35. *
  36. * @return string
  37. */
  38. public function renderContent()
  39. {
  40. $content = parent::renderContent();
  41. $footer = $this->renderFooter();
  42. return <<<HTML
  43. <div class="card-content">
  44. <div class="row">
  45. {$content}
  46. </div>
  47. <div class="metric-footer">
  48. {$footer}
  49. </div>
  50. </div>
  51. HTML;
  52. }
  53. }

启用以及渲染图表

基本卡片默认是启用图表功能的,通过useChart方法可以启用图表功能,调用此方法之后会实例化一个图表类,然后保存在chart属性当中。

当图表启用之后,还需要在你的卡片内容中渲染图表,否则图表虽然被初始化了,但是仍无法显示。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. // 启用图表
  7. $this->useChart();
  8. }
  9. /**
  10. * 渲染卡片内容
  11. * 需要在这里加上渲染图表的代码
  12. *
  13. * @return string
  14. */
  15. public function renderContent()
  16. {
  17. // 通过 content 方法设置的内容
  18. $content = parent::renderContent();
  19. // 渲染图表
  20. $chart = $this->renderChart();
  21. return <<<HTML
  22. <div class="my-chart">{$chart}</div>
  23. {$content}
  24. HTML
  25. }
  26. }

图表默认配置 (defaultChartOptions)

通过defaultChartOptions方法可以设置图表默认配置,此方法只有启用图表之后才有效。

{tip} 这里的图表配置同样支持设置可执行JS代码,详细用法请参考图表配置设置可执行JS代码

  1. class MyCard extend Card
  2. {
  3. protected function defaultChartOptions()
  4. {
  5. // 返回图表的配置
  6. return [
  7. ...
  8. ];
  9. }
  10. }

设置图表 (chart)

通过chart方法可以设置图表配置。

{tip} 这里的图表配置同样支持设置可执行JS代码,详细用法请参考图表配置设置可执行JS代码

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->chart([...]);
  7. }
  8. }

设置图表配置 (chartOption)

通过chartOption方法可以设置图表配置,此方法一次只能设置一个参数,支持设置多维参数。

{tip} 这里的图表配置同样支持设置可执行JS代码,详细用法请参考图表配置设置可执行JS代码

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->chartOption('stroke.curve', 'smooth');
  7. $this->chartOption(
  8. 'plotOptions.radialBar.dataLabels.total.formatter',
  9. // 这个值最后段代码会作为JS代码执行
  10. JavaScript::make("function () { return {$number}; }")
  11. );
  12. }
  13. }

设置图表高度 (chartHeight)

通过chartHeight方法可以设置图表的高度,这个方法非常重要,经常需要结合height方法一起使用,调整卡片的整体高度。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->chartHeight(150);
  7. }
  8. }

设置图表上间距 (chartMarginTop)

通过chartMarginTop方法可以设置图表与上级元素的间距,此方法接受一个int类型参数,可以传负数

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->chartMarginTop(-10);
  7. }
  8. }

设置图表下间距 (chartMarginBottom)

通过chartMarginBottom方法可以设置图表与下级元素的间距,此方法接受一个int类型参数,可以传负数

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->chartMarginBottom(10);
  7. }
  8. }

设置图表标签 (chartLabels)

通过chartLabels方法可以设置图表的标签(labels)配置。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->chartLabels('标签1');
  7. // 也可以传递数组
  8. $this->chartLabels(['标签1']);
  9. }
  10. }

设置图表颜色 (chartColors)

通过chartColors方法可以设置图表的颜色(colors)配置。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. $this->chartColors('#4f41a1');
  7. // 也可以传递数组
  8. $this->chartColors(['#4f41a1']);
  9. }
  10. }

渲染图表 (renderChart)

通过renderChart方法可以渲染图表。

  1. class MyCard extend Card
  2. {
  3. protected function init()
  4. {
  5. parent::init();
  6. // 启用图表
  7. $this->useChart();
  8. }
  9. /**
  10. * 渲染卡片内容
  11. * 需要在这里加上渲染图表的代码
  12. *
  13. * @return string
  14. */
  15. public function renderContent()
  16. {
  17. // 通过 content 方法设置的内容
  18. $content = parent::renderContent();
  19. // 渲染图表
  20. $chart = $this->renderChart();
  21. return <<<HTML
  22. <div class="my-chart">{$chart}</div>
  23. {$content}
  24. HTML
  25. }
  26. }

线性趋势图卡片 (Line)

线性趋势图卡片(Dcat\Admin\Widgets\Metrics\Line)是一个附带了折线\曲线图的数据统计卡片,继承自基础卡片Dcat\Admin\Widgets\Metrics\Card

数据统计卡片 - 图2

示例

可参考内置的App\Admin\Metrics\Examples\NewUsers类。

  1. <?php
  2. namespace App\Admin\Metrics\Examples;
  3. use Dcat\Admin\Widgets\Metrics\Line;
  4. use Illuminate\Http\Request;
  5. class NewUsers extends Line
  6. {
  7. /**
  8. * @var string
  9. */
  10. protected $label = 'New Users';
  11. /**
  12. * 初始化卡片内容
  13. *
  14. * @return void
  15. */
  16. protected function init()
  17. {
  18. parent::init();
  19. $this->title($this->label);
  20. $this->dropdown([
  21. '7' => 'Last 7 Days',
  22. '28' => 'Last 28 Days',
  23. '30' => 'Last Month',
  24. '365' => 'Last Year',
  25. ]);
  26. }
  27. /**
  28. * 处理请求
  29. *
  30. * @param Request $request
  31. *
  32. * @return mixed|void
  33. */
  34. public function handle(Request $request)
  35. {
  36. $generator = function ($len, $min = 10, $max = 300) {
  37. for ($i = 0; $i <= $len; $i++) {
  38. yield mt_rand($min, $max);
  39. }
  40. };
  41. switch ($request->get('option')) {
  42. case '365':
  43. // 卡片内容
  44. $this->withContent(mt_rand(1000, 5000).'k');
  45. // 图表数据
  46. $this->withChart(collect($generator(30))->toArray());
  47. // 直线
  48. break;
  49. case '30':
  50. // 卡片内容
  51. $this->withContent(mt_rand(400, 1000).'k');
  52. // 图表数据
  53. $this->withChart(collect($generator(30))->toArray());
  54. // 直线
  55. break;
  56. case '28':
  57. // 卡片内容
  58. $this->withContent(mt_rand(400, 1000).'k');
  59. // 图表数据
  60. $this->withChart(collect($generator(28))->toArray());
  61. // 直线
  62. break;
  63. case '7':
  64. default:
  65. // 卡片内容
  66. $this->withContent('89.2k');
  67. // 图表数据
  68. $this->withChart([28, 40, 36, 52, 38, 60, 55,]);
  69. }
  70. }
  71. /**
  72. * 设置图表数据.
  73. *
  74. * @param array $data
  75. *
  76. * @return $this
  77. */
  78. public function withChart(array $data)
  79. {
  80. return $this->chart([
  81. 'series' => [
  82. [
  83. 'name' => $this->label,
  84. 'data' => $data,
  85. ],
  86. ],
  87. ]);
  88. }
  89. /**
  90. * 设置卡片内容.
  91. *
  92. * @param string $content
  93. *
  94. * @return $this
  95. */
  96. public function withContent($content)
  97. {
  98. return $this->content(
  99. <<<HTML
  100. <div class="d-flex justify-content-between align-items-center mt-1" style="margin-bottom: 2px">
  101. <h2 class="ml-1 font-large-1">{$content}</h2>
  102. <span class="mb-0 mr-1 text-80">{$this->label}</span>
  103. </div>
  104. HTML
  105. );
  106. }
  107. }

方法

设置线条为直线 (chartStraight)

  1. use Dcat\Admin\Widgets\Metrics\Line;
  2. class MyCard extend Line
  3. {
  4. protected function init()
  5. {
  6. parent::init();
  7. $this->chartStraight();
  8. }
  9. }

设置线条为曲线 (chartSmooth)

默认显示的是曲线。

  1. use Dcat\Admin\Widgets\Metrics\Line;
  2. class MyCard extend Line
  3. {
  4. protected function init()
  5. {
  6. parent::init();
  7. $this->chartSmooth();
  8. }
  9. }

圆环图卡片 (Donut)

圆环图卡片(Dcat\Admin\Widgets\Metrics\Donut)是一个附带了圆环图的数据统计卡片,继承自基础卡片Dcat\Admin\Widgets\Metrics\Card

数据统计卡片 - 图3

示例

可参考内置的App\Admin\Metrics\Examples\NewDevices类。

  1. <?php
  2. namespace App\Admin\Metrics\Examples;
  3. use Dcat\Admin\Admin;
  4. use Dcat\Admin\Widgets\Metrics\Donut;
  5. class NewDevices extends Donut
  6. {
  7. protected $labels = ['Desktop', 'Mobile'];
  8. /**
  9. * 初始化卡片内容
  10. */
  11. protected function init()
  12. {
  13. parent::init();
  14. $color = Admin::color();
  15. $colors = [$color->primary(), $color->alpha('blue2', 0.5)];
  16. $this->title('New Devices');
  17. $this->subTitle('Last 30 days');
  18. $this->chartLabels($this->labels);
  19. // 设置图表颜色
  20. $this->chartColors($colors);
  21. }
  22. /**
  23. * 渲染模板
  24. *
  25. * @return string
  26. */
  27. public function render()
  28. {
  29. $this->fill();
  30. return parent::render();
  31. }
  32. /**
  33. * 写入数据.
  34. *
  35. * @return void
  36. */
  37. public function fill()
  38. {
  39. $this->withContent(44.9, 28.6);
  40. // 图表数据
  41. $this->withChart([44.9, 28.6]);
  42. }
  43. /**
  44. * 设置图表数据.
  45. *
  46. * @param array $data
  47. *
  48. * @return $this
  49. */
  50. public function withChart(array $data)
  51. {
  52. return $this->chart([
  53. 'series' => $data
  54. ]);
  55. }
  56. /**
  57. * 设置卡片头部内容.
  58. *
  59. * @param mixed $desktop
  60. * @param mixed $mobile
  61. *
  62. * @return $this
  63. */
  64. protected function withContent($desktop, $mobile)
  65. {
  66. $blue = Admin::color()->alpha('blue2', 0.5);
  67. $style = 'margin-bottom: 8px';
  68. $labelWidth = 120;
  69. return $this->content(
  70. <<<HTML
  71. <div class="d-flex pl-1 pr-1 pt-1" style="{$style}">
  72. <div style="width: {$labelWidth}px">
  73. <i class="fa fa-circle text-primary"></i> {$this->labels[0]}
  74. </div>
  75. <div>{$desktop}</div>
  76. </div>
  77. <div class="d-flex pl-1 pr-1" style="{$style}">
  78. <div style="width: {$labelWidth}px">
  79. <i class="fa fa-circle" style="color: $blue"></i> {$this->labels[1]}
  80. </div>
  81. <div>{$mobile}</div>
  82. </div>
  83. HTML
  84. );
  85. }
  86. }

方法

设置内容宽度 (contentWidth)

通过contentWidth方法可以设置文本内容以及图表内容的宽度,默认为[6, 6]

{tip} 这里的宽度是一个1-12之间的一个值。

  1. use Dcat\Admin\Widgets\Metrics\Line;
  2. class MyCard extend Line
  3. {
  4. protected function init()
  5. {
  6. parent::init();
  7. $this->contentWidth(4, 8);
  8. }
  9. }

柱状图卡片 (Bar)

柱状图卡片(Dcat\Admin\Widgets\Metrics\Bar)是一个附带了柱状图的数据统计卡片,继承自基础卡片Dcat\Admin\Widgets\Metrics\Card

数据统计卡片 - 图4

示例

可参考内置的App\Admin\Metrics\Examples\NewDevices类。

  1. <?php
  2. namespace App\Admin\Metrics\Examples;
  3. use Dcat\Admin\Admin;
  4. use Dcat\Admin\Widgets\Metrics\Bar;
  5. use Illuminate\Http\Request;
  6. class Sessions extends Bar
  7. {
  8. /**
  9. * 初始化卡片内容
  10. */
  11. public function init()
  12. {
  13. parent::init();
  14. $color = Admin::color();
  15. $dark35 = $color->dark35();
  16. // 卡片内容宽度
  17. $this->contentWidth(5, 7);
  18. // 标题
  19. $this->title('Avg Sessions');
  20. // 设置下拉选项
  21. $this->dropdown([
  22. '7' => 'Last 7 Days',
  23. '28' => 'Last 28 Days',
  24. '30' => 'Last Month',
  25. '365' => 'Last Year',
  26. ]);
  27. // 设置图表颜色
  28. $this->chartColors([
  29. $dark35,
  30. $dark35,
  31. $color->primary(),
  32. $dark35,
  33. $dark35,
  34. $dark35
  35. ]);
  36. }
  37. /**
  38. * 处理请求
  39. *
  40. * @param Request $request
  41. *
  42. * @return mixed|void
  43. */
  44. public function handle(Request $request)
  45. {
  46. switch ($request->get('option')) {
  47. case '7':
  48. default:
  49. // 卡片内容
  50. $this->withContent('2.7k', '+5.2%');
  51. // 图表数据
  52. $this->withChart([
  53. [
  54. 'name' => 'Sessions',
  55. 'data' => [75, 125, 225, 175, 125, 75, 25],
  56. ],
  57. ]);
  58. }
  59. }
  60. /**
  61. * 设置图表数据.
  62. *
  63. * @param array $data
  64. *
  65. * @return $this
  66. */
  67. public function withChart(array $data)
  68. {
  69. return $this->chart([
  70. 'series' => $data,
  71. ]);
  72. }
  73. /**
  74. * 设置卡片内容.
  75. *
  76. * @param string $title
  77. * @param string $value
  78. * @param string $style
  79. *
  80. * @return $this
  81. */
  82. public function withContent($title, $value, $style = 'success')
  83. {
  84. // 根据选项显示
  85. $label = strtolower(
  86. $this->dropdown[request()->option] ?? 'last 7 days'
  87. );
  88. $minHeight = '183px';
  89. return $this->content(
  90. <<<HTML
  91. <div class="d-flex p-1 flex-column justify-content-between" style="padding-top: 0;width: 100%;height: 100%;min-height: {$minHeight}">
  92. <div class="text-left">
  93. <h1 class="font-large-2 mt-2 mb-0">{$title}</h1>
  94. <h5 class="font-medium-2" style="margin-top: 10px;">
  95. <span class="text-{$style}">{$value} </span>
  96. <span>vs {$label}</span>
  97. </h5>
  98. </div>
  99. <a href="#" class="btn btn-primary shadow waves-effect waves-light">View Details <i class="feather icon-chevrons-right"></i></a>
  100. </div>
  101. HTML
  102. );
  103. }
  104. }

多环形图卡片 (Round)

柱状图卡片(Dcat\Admin\Widgets\Metrics\Round)是一个附带了多环形图的数据统计卡片,继承自基础卡片Dcat\Admin\Widgets\Metrics\Card

数据统计卡片 - 图5

示例

具体示例与上述卡片的示例大同小异,具体可参考内置的App\Admin\Metrics\Examples\ProductOrders类,这里不再贴出。

更多内置卡片

系统还内置了Dcat\Admin\Widgets\Metrics\RadialBarDcat\Admin\Widgets\Metrics\SingleRound等卡片,由于用法与上述卡片雷同,这里不再重复贴出代码。

点击我查看所有内置卡片在线演示

自定义图表卡片

如需自定义卡片,可参考上述内置图表的代码。