数据大屏模块（screen）

一、模块简介

screen 是基于 ZTBCMS 开发的数据大屏应用模块，用于快速制作可视化数据大屏、科技大屏、运营看板和实时统计展示页。

模块提供后台可视化编辑能力，支持拖拽组件、调整位置与大小、配置图表数据、绑定实时数据源，并通过公开展示页进行大屏播放。

本模块采用非构建方式实现，不依赖 Vite、Webpack、Node.js 打包流程。前端直接复用 ZTBCMS 后台已有的 Vue、Element UI、jQuery，并通过内置渲染脚本完成图表展示。

二、功能清单

1. 大屏管理

新增大屏
编辑大屏
删除大屏
草稿 / 发布状态切换
大屏预览
复制访问链接
内置演示大屏

2. 可视化编辑器

左侧组件库拖拽添加组件
中间画布实时预览
右侧属性面板修改组件
支持组件移动
支持组件缩放
支持组件复制
支持组件删除
支持画布宽高配置
支持画布背景色配置
支持画布背景图配置

3. 内置组件

纯文本
滚动文本
当前时间文本
图片
视频
指标卡片
柱状图
折线图
占比图
仪表盘
数据表格

4. 数据源能力

模拟数据源
静态 JSON 数据源
接口 JSON 数据源
数据源测试
组件绑定数据源
展示页定时刷新

三、目录结构

tp6/app/screen/
├── Config.inc.php                         模块基础信息
├── controller/
│   ├── Viewer.php                         前台展示与公开数据接口
│   └── admin/
│       ├── Report.php                     大屏后台管理
│       └── Datasource.php                 数据源后台管理
├── install/
│   ├── Menu.php                           后台菜单安装配置
│   ├── Screen.sql                         安装数据表
│   └── extra/
│       ├── css/screen.css                 大屏展示样式
│       └── js/screen-renderer.js          大屏渲染脚本
├── model/
│   ├── ScreenReportModel.php              大屏数据模型
│   └── ScreenDatasourceModel.php          数据源数据模型
├── service/
│   ├── ScreenReportService.php            大屏业务服务
│   └── ScreenDatasourceService.php        数据源业务服务
├── uninstall/
│   └── Screen.sql                         卸载数据表
└── view/
    ├── admin/
    │   ├── report/                        大屏管理页面
    │   └── datasource/                    数据源管理页面
    └── viewer/index.php                   前台展示页面

四、安装说明

1. 环境要求

PHP 版本：遵循 ZTBCMS 当前项目要求
MySQL：遵循 ZTBCMS 当前项目要求
已安装 ZTBCMS
已能正常访问后台

如果需要使用接口数据源，建议 PHP 开启 curl 扩展。

2. 后台安装

登录 ZTBCMS 后台，进入：

模块管理 -> 本地模块 -> 数据大屏 -> 安装

安装成功后，会自动创建数据表并注册后台菜单。

3. 命令行安装

也可以在 tp6/ 目录下执行：

php think module:install screen

4. 安装后菜单

安装后后台会出现：

数据大屏
├── 大屏管理
└── 数据源管理

五、静态资源说明

模块安装时会把资源复制到公开目录：

tp6/public/statics/extra/screen/css/screen.css
tp6/public/statics/extra/screen/js/screen-renderer.js

如果手动部署后页面样式或图表不显示，请确认上述文件存在。

公开访问路径为：

/statics/extra/screen/css/screen.css
/statics/extra/screen/js/screen-renderer.js

六、快速开始

1. 查看演示大屏

安装模块前，也可以直接访问内置演示页：

/screen/viewer/index?code=demo

演示页不依赖数据库数据，用于确认展示页和静态资源是否正常。

2. 创建数据源

进入：

数据大屏 -> 数据源管理 -> 新增数据源

可选择三种数据类型：

类型	适用场景
模拟数据	调试、演示、没有接口时快速预览
静态 JSON	固定数据、临时数据、离线展示
接口数据	对接业务系统实时数据

保存后可以点击“测试”，确认返回数据是否正确。

3. 创建大屏

进入：

数据大屏 -> 大屏管理 -> 新增大屏

制作流程：

从左侧组件库拖拽组件到画布。
点击画布中的组件。
在左侧画布区域设置背景色、背景图地址和背景图模式。
在右侧修改组件标题、位置、大小、颜色和数据。
文本组件可选择纯文本、滚动文本或当前时间。
图片、视频组件填写资源地址即可展示。
如需实时数据，在右侧绑定数据源。
点击“保存”或“保存并预览”。

4. 访问正式大屏

大屏保存并发布后，使用以下地址访问：

/screen/viewer/index?code=大屏编码

例如：

/screen/viewer/index?code=sales_dashboard

展示页会自动按浏览器窗口等比缩放，适合电视、投屏、大屏浏览器全屏展示。

七、数据格式说明

1. 画布背景图配置

大屏画布支持背景色和背景图。背景图填写可访问的图片地址即可，例如：

/uploads/screen/bg.jpg
https://example.com/screen/bg.jpg

背景图模式支持：

覆盖画布：图片铺满画布，适合 16:9 背景图。
完整显示：图片完整显示，可能留边。
原始尺寸：按图片原始尺寸展示。

2. 文本组件格式

纯文本和滚动文本使用：

{
  "mode": "normal",
  "text": "智慧运营数据中心",
  "format": "YYYY-MM-DD HH:mm:ss"
}

滚动文本将 mode 设置为：

{
  "mode": "scroll",
  "text": "重要数据持续更新中，请关注最新业务动态"
}

当前时间文本将 mode 设置为：

{
  "mode": "time",
  "format": "YYYY-MM-DD HH:mm:ss"
}

3. 图片组件格式

{
  "url": "/uploads/screen/example.jpg"
}

图片地址可以是站内路径，也可以是完整的外部 URL。

4. 视频组件格式

{
  "url": "/uploads/screen/demo.mp4",
  "autoplay": true,
  "loop": true,
  "muted": true,
  "controls": false
}

浏览器通常要求自动播放视频必须静音，因此建议保留 muted: true。

5. 图表通用格式

柱状图、折线图、占比图优先识别 items：

{
  "items": [
    {"name": "华东", "value": 86},
    {"name": "华南", "value": 72},
    {"name": "华北", "value": 63}
  ]
}

6. 指标卡片格式

{
  "value": 9862,
  "unit": "次",
  "trend": "+9.6%"
}

7. 仪表盘格式

{
  "value": 76
}

value 建议为 0 - 100。

8. 表格格式

{
  "columns": ["时间", "事件", "状态"],
  "rows": [
    ["09:30", "订单同步完成", "正常"],
    ["10:00", "接口巡检完成", "正常"]
  ]
}

八、接口数据源说明

接口数据源只处理 JSON 响应。

1. 普通接口返回

如果接口直接返回：

{
  "items": [
    {"name": "A", "value": 40},
    {"name": "B", "value": 68}
  ]
}

则“响应路径”留空即可。

2. 嵌套接口返回

如果接口返回：

{
  "status": true,
  "data": {
    "items": [
      {"name": "A", "value": 40},
      {"name": "B", "value": 68}
    ]
  }
}

则“响应路径”填写：

data

如果接口返回更深层结构：

{
  "status": true,
  "data": {
    "chart": {
      "items": [
        {"name": "A", "value": 40}
      ]
    }
  }
}

则“响应路径”填写：

data.chart

九、页面与接口地址

1. 后台页面

/screen/admin.Report/index
/screen/admin.Report/add
/screen/admin.Report/edit?report_id=1
/screen/admin.Datasource/index
/screen/admin.Datasource/add
/screen/admin.Datasource/edit?source_id=1

2. 前台展示

/screen/viewer/index?code=demo
/screen/viewer/index?code=大屏编码

3. 公开数据接口

/screen/viewer/report?code=大屏编码
/screen/viewer/data?source_code=数据源编码

十、数据表

安装后会创建：

cms_screen_report
cms_screen_datasource

系统会根据当前项目数据库表前缀自动替换 cms_。

1. 大屏表

用于保存大屏名称、编码、状态、排序和画布配置。

2. 数据源表

用于保存数据源名称、编码、类型、接口地址、静态数据和刷新间隔。

十一、上线部署说明

上线前请确认：

模块已安装成功。
后台菜单可正常打开。
静态资源文件已复制到公开目录。
大屏状态为“发布”。
公开展示地址可正常访问。
业务接口可被服务器正常访问。
接口返回为 JSON。
投屏设备浏览器能访问站点域名。

建议上线后先访问：

/screen/viewer/index?code=demo

确认演示大屏正常后，再访问正式大屏。

十二、验收步骤

1. 基础验收

后台能看到“数据大屏”菜单。
能打开“大屏管理”。
能打开“数据源管理”。
能访问演示大屏。

2. 制作验收

新增一个数据源。
点击测试，确认有数据返回。
新增一个大屏。
新增页面应正常显示设计器，页面不能空白。
组件库应能看到纯文本、滚动文本、当前时间、图片、视频、指标卡片和图表组件。
设置画布背景图，确认保存后预览页能正常展示。
拖入至少一个指标卡片和一个图表组件。
拖入纯文本、滚动文本、当前时间、图片、视频组件，确认内容能正常展示。
绑定数据源。
保存并预览。
展示页能正常显示图表和媒体内容。

3. 边界验收

访问不存在的大屏编码，应提示“大屏不存在或未发布”。
访问不存在的数据源编码，应提示“数据源不存在或已禁用”。
静态 JSON 填写错误时，保存应失败并提示。
接口返回非 JSON 时，测试应失败并提示。

十三、常见问题

1. 页面样式丢失或图表不显示

请确认静态资源是否存在：

tp6/public/statics/extra/screen/css/screen.css
tp6/public/statics/extra/screen/js/screen-renderer.js

如果不存在，重新安装模块，或手动复制 install/extra 中的资源。

2. 接口数据源测试失败

请检查：

接口地址是否正确
PHP 运行环境是否能访问接口
接口是否返回 JSON
如接口有嵌套，响应路径是否填写正确

3. 大屏访问提示不存在或未发布

请检查：

大屏编码是否正确
大屏状态是否为“发布”
模块是否已安装
数据表是否存在

4. 投屏时比例不合适

展示页会按窗口等比缩放。建议：

浏览器开启全屏
大屏画布按目标分辨率设置，例如 1920 x 1080
投屏设备使用 16:9 分辨率

5. 新增大屏页面空白或 500

如果访问下面地址时页面空白或返回 500：

/screen/admin.Report/add

请按下面顺序检查：

先清理缓存：

cd tp6
php think clear

确认模块静态资源存在：

tp6/public/statics/extra/screen/css/screen.css
tp6/public/statics/extra/screen/js/screen-renderer.js

确认模块数据库已安装完成，至少存在下面数据表：

cms_screen_report
cms_screen_datasource

确认当前后台账号已登录，并且有“数据大屏”菜单权限。
如果修改过编辑器页面，请注意 JavaScript 对象中的 url 建议写成带引号的形式，例如：

{'url': ''}

不要写成容易被模板解析器误识别的形式：

{url: ''}

检查服务器错误日志，确认没有缺少表、缺少权限、缺少静态文件等问题。

十四、卸载说明

后台卸载路径：

模块管理 -> 已安装模块 -> 数据大屏 -> 卸载

命令行卸载：

php think module:uninstall screen

卸载会删除：

cms_screen_report
cms_screen_datasource

卸载不会删除模块源码目录。

十五、版本信息

模块名称：screen
显示名称：数据大屏
当前版本：1.0.0
适配版本：ZTBCMS 4.0.0+

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
controller		controller
install		install
model		model
service		service
uninstall		uninstall
view		view
Config.inc.php		Config.inc.php
readme.md		readme.md

Folders and files

Latest commit

History

Repository files navigation

数据大屏模块（screen）

一、模块简介

二、功能清单

1. 大屏管理

2. 可视化编辑器

3. 内置组件

4. 数据源能力

三、目录结构

四、安装说明

1. 环境要求

2. 后台安装

3. 命令行安装

4. 安装后菜单

五、静态资源说明

六、快速开始

1. 查看演示大屏

2. 创建数据源

3. 创建大屏

4. 访问正式大屏

七、数据格式说明

1. 画布背景图配置

2. 文本组件格式

3. 图片组件格式

4. 视频组件格式

5. 图表通用格式

6. 指标卡片格式

7. 仪表盘格式

8. 表格格式

八、接口数据源说明

1. 普通接口返回

2. 嵌套接口返回

九、页面与接口地址

1. 后台页面

2. 前台展示

3. 公开数据接口

十、数据表

1. 大屏表

2. 数据源表

十一、上线部署说明

十二、验收步骤

1. 基础验收

2. 制作验收

3. 边界验收

十三、常见问题

1. 页面样式丢失或图表不显示

2. 接口数据源测试失败

3. 大屏访问提示不存在或未发布

4. 投屏时比例不合适

5. 新增大屏页面空白或 500

十四、卸载说明

十五、版本信息

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages