Skills — 大屏自动生成

1. 功能介绍

jimubi-bigscreen 是 Claude Code 的 AI Skill，能够将自然语言的大屏需求转换为 drag page 配置，并通过 API 自动创建全屏数据可视化大屏。

核心能力：

全屏展示模式，绝对定位（像素坐标），深色主题
默认 1920×1080 分辨率，适用于监控室/展厅/展示墙
丰富组件支持：数字翻牌、折线图、柱状图、饼图、地图、滚动表格、排行榜等
装饰元素：边框（JDragBorder）、装饰条（JDragDecoration）增强视觉效果
自定义背景图和主题配色
支持静态数据和动态数据集（SQL/API/JSON/WebSocket）

注意：大屏与仪表盘使用完全不同的布局和样式体系，仪表盘请使用 jimubi-dashboard。

不确定该用哪个 Skill？请查看 AI Skills 技能清单。下载地址：https://github.com/jeecgboot/skills

2. 前置条件

使用前需要准备两个信息：

信息	获取方式	示例
API 地址	JeecgBoot 后端服务地址	`https://api3.boot.jeecg.com`
X-Access-Token	浏览器 F12 → Network → 任意请求的 Request Headers	`eyJhbGciOiJIUzI1NiIs...`

3. 使用方式

在 Claude Code 中直接用自然语言描述大屏需求即可。以下是触发关键词：

创建大屏、生成大屏、新建大屏、设计大屏、做一个大屏、
BI大屏、数据大屏、可视化大屏、监控大屏、
展厅展示、监控室大屏、
create big screen、design big screen

4. 大屏特征

特征	说明
布局方式	绝对定位，坐标和尺寸单位为像素（如 x=50, y=280, w=860, h=380）
默认主题	`dark`，深色背景，亮色/霓虹文字
背景图	默认 `/img/bg/bg4.png`，支持自定义
装饰元素	常用 JDragBorder（边框）、JDragDecoration（装饰条）增强视觉效果
典型分辨率	1920×1080

大屏样式预设（bi_utils.py 自动应用）：

背景：透明 rgba(0,0,0,0)
文字颜色：白色 #ffffff
轴标签：白色 #ffffff
网格线：rgba(255,255,255,0.1)
表格：深色背景 + 白色文字

5. 支持的组件类型

5.1 常用大屏组件速查

用户描述关键词	组件 component	说明
数字/KPI/指标	`JNumber`	数字指标卡
翻牌器/数字动画	`JCountTo`	数字翻牌器
柱状图	`JBar`	基础柱状图
横向柱状图	`JHorizontalBar`	水平柱状图
堆叠柱状图	`JStackBar`	堆叠柱状图
折线图/趋势	`JLine`	折线图
曲线图	`JSmoothLine`	平滑曲线
柱线混合	`JMixLineBar`	柱状+折线混合
饼图	`JPie`	饼图
环形图	`JRing`	环形图
玫瑰图	`JRose`	南丁格尔玫瑰图
仪表盘/表盘	`JGauge`	仪表盘表盘
水球图	`JLiquid`	水球图
进度条	`JProgress`	进度条
雷达图	`JRadar`	雷达图
漏斗图	`JFunnel`	漏斗图
词云	`JWordCloud`	词云图
地图/区域地图	`JAreaMap`	区域地图
飞线地图/迁徙	`JFlyLineMap`	飞线地图
热力地图	`JHeatMap`	热力地图
滚动表格	`JScrollTable`	自动滚动表格
排行榜/排名	`JScrollRankingBoard`	滚动排行榜
文本/标题	`JText`	文本显示
图片	`JImg`	图片
视频	`JVideoPlay`	视频播放
边框/装饰	`JDragBorder`	装饰边框（13种样式）
装饰条	`JDragDecoration`	装饰条（12种样式）
时钟	`JCurrentTime`	实时时钟

5.2 装饰元素

大屏特有的装饰元素，用于增强视觉效果：

JDragBorder：装饰边框，13 种样式可选，常用于包裹图表区域
JDragDecoration：装饰条，12 种样式可选，常用于标题区域和分隔线

6. 交互流程

Step 1: 解析用户需求

AI 从用户描述中提取：

信息	默认值	示例
页面名称	用户指定	"销售数据大屏"
主题	dark	dark
背景图	`/img/bg/bg4.png`	可自定义
组件列表	从描述中解析	销售额(数字)、订单趋势(折线图)、区域分布(地图)

Step 2: 展示设计摘要并确认

AI 展示大屏设计摘要，包括页面名称、主题、组件列表（名称、类型、位置、尺寸、数据源），等待用户确认后执行。

Step 3: 调用 API 创建大屏

使用共通工具库 bi_utils.py 创建大屏：

from bi_utils import *

init_api('https://api3.boot.jeecg.com', 'your-token')

# 创建大屏（style='bigScreen'，像素坐标）
page_id = create_page('销售数据大屏', style='bigScreen', theme='dark',
                       background_image='/img/bg/bg4.png')

# 页面主标题
add_text(page_id, 'CRM 数据大屏', x=560, y=15, w=800, h=60,
         font_size=42, color='#ffffff', font_weight='bold',
         text_align='center', letter_spacing=5)

# 数字指标
add_number(page_id, '今日销售额', x=50, y=100, w=400, h=200,
           value=128560, prefix='¥', suffix='元')

# 折线图
add_chart(page_id, 'JLine', '销售趋势', x=50, y=320, w=860, h=380,
          categories=['1月','2月','3月','4月','5月','6月'],
          series=[{'name':'销售额', 'data':[820,932,901,934,1290,1330]}])

# 柱状图
add_chart(page_id, 'JBar', '部门业绩', x=950, y=320, w=860, h=380,
          categories=['研发部','销售部','市场部','运营部'],
          series=[{'name':'业绩', 'data':[320,302,341,374]}])

# 饼图
add_chart(page_id, 'JPie', '客户来源', x=50, y=700, w=500, h=350,
          pie_data=[
              {'name':'直接访问', 'value':335},
              {'name':'邮件营销', 'value':310},
              {'name':'联盟广告', 'value':234},
          ])

# 装饰元素
add_border(page_id, x=30, y=80, w=440, h=240, border_type=1, color='#00BAFF')
add_decoration(page_id, x=660, y=20, w=600, h=60, deco_type=5, color='#00BAFF')

save_page(page_id)
print(f'大屏创建成功！ID: {page_id}')

Step 4: 输出结果

创建完成后输出页面 ID、名称、预览地址和组件数量。

7. 可用的快捷函数

API 初始化

init_api(api_base, token) — 初始化 API 地址和 Token

页面管理

create_page(name, style='bigScreen', theme='dark', background_image, type_id, design_type) — 创建大屏
query_page(page_id) — 查询页面详情
list_pages(style='bigScreen') — 列表查询
save_page(page_id) — 保存设计
delete_page(page_id, physical) — 删除
recover_page(page_id) — 恢复
copy_page(page_id) — 复制

添加组件（像素坐标）

add_number(page_id, title, x, y, w, h, value, prefix, suffix) — 数字指标
add_chart(page_id, chart_type, title, x, y, w, h, categories, series, pie_data) — 图表
add_table(page_id, title, x, y, w, h, columns, data) — 数据表格
add_scroll_table(page_id, title, x, y, w, h, columns, data) — 滚动表格
add_ranking(page_id, title, x, y, w, h, data) — 排行榜
add_text(page_id, title, x, y, w, h, content, font_size, color) — 文本
add_image(page_id, title, x, y, w, h, src) — 图片
add_gauge(page_id, title, x, y, w, h, value, max_val, unit, color) — 仪表盘表盘
add_liquid(page_id, title, x, y, w, h, value, color) — 水球图
add_countdown(page_id, title, x, y, w, h, value, font_size, color) — 翻牌器
add_border(page_id, x, y, w, h, border_type, color) — 装饰边框
add_decoration(page_id, x, y, w, h, deco_type, color) — 装饰条
add_component(page_id, component, title, x, y, w, h, config) — 通用组件

8. 大屏标题规则

card.title 必须为空

大屏模式下，所有图表组件的 option.card.title 必须为空字符串 ''。图表标题只通过 option.title.text 显示（ECharts 内部标题）。

原因： card.title 会在组件顶部生成一个白色背景的卡片头部条，与深色大屏背景严重冲突，且与 ECharts 的 option.title 形成双重标题。bi_utils.py 已自动处理此逻辑。

大屏页面主标题用 JText

推荐配置：fontSize 40+、fontWeight 'bold'、letterSpacing 5、color #ffffff。

装饰元素使用建议

JDragBorder 和 JDragDecoration 适合用在图表区域的边框装饰
标题区域只用 JText 或 JImg，不使用 JDragDecoration

9. 数据集管理（动态数据源）

大屏组件支持三种数据类型（config.dataType）：

dataType	说明
`1`	静态数据（直接写在 chartData 中）
`2`	动态数据（从数据集获取，支持 SQL/API/JSON/WebSocket）
`4`	表单数据（从表单关联字段查询）

数据集 API 端点

端点	方法	说明
`/drag/onlDragDatasetHead/add`	POST	创建数据集
`/drag/onlDragDatasetHead/edit`	POST	编辑数据集
`/drag/onlDragDatasetHead/delete?id=xxx`	DELETE	删除数据集
`/drag/onlDragDatasetHead/list`	GET	分页查询数据集列表
`/drag/onlDragDatasetHead/getAllChartData`	POST	执行数据集查询
`/drag/onlDragDatasetHead/queryFieldBySql`	POST	解析 SQL 返回字段列表

组件绑定数据集

组件的 config 中设置 dataType: 2 并配置 dataSetId、dataSetType、dataMapping 等字段实现动态数据绑定。

字段映射规则：

映射标签（filed）	标准字段	说明
`维度` / `名称`	`name`	图表类目/维度
`数值`	`value`	图表数值
`分组`	`type`	多系列区分字段

注意：dataMapping 中的键名是 filed（不是 field），这是系统设计。

10. 编辑与删除

编辑已有大屏

from bi_utils import *
init_api('https://api3.boot.jeecg.com', 'your-token')

page = query_page(page_id)
add_chart(page_id, 'JBar', '新增图表', x=0, y=500, w=600, h=300,
          categories=['A','B','C'], series=[{'name':'值','data':[10,20,30]}])
save_page(page_id)

删除大屏

delete_page(page_id)                # 软删除
delete_page(page_id, physical=True) # 硬删除
recover_page(page_id)               # 恢复

11. 常见问题

问题	解决方案
Token 过期（401）	重新获取 X-Access-Token
`updateCount` 不匹配	重新查询页面获取最新值
组件不显示	检查 dataType、chartData（必须是 JSON 字符串）、option 是否完整
新增组件被遮挡	设 `orderNum: 300` 提高层级
标题重复	图表 `option.card.title` 设为空，仅用 `option.title.text`
布局错乱	确认使用像素坐标（不是栅格）
chartData 不渲染	`config.chartData` 必须是 `json.dumps(...)` 后的字符串
多系列图表格式	chartData 需要 `type` 字段区分系列
HTTPS 连接问题	api3.boot.jeecg.com 使用 HTTP 协议
页签切换不工作	检查 JTabToggle 的 `compVals` 是否指向正确的组件 ID

1. 功能介绍​

2. 前置条件​

3. 使用方式​

4. 大屏特征​

5. 支持的组件类型​

5.1 常用大屏组件速查​

5.2 装饰元素​

6. 交互流程​

Step 1: 解析用户需求​

Step 2: 展示设计摘要并确认​

Step 3: 调用 API 创建大屏​

Step 4: 输出结果​

7. 可用的快捷函数​

API 初始化​

页面管理​

添加组件（像素坐标）​

8. 大屏标题规则​

card.title 必须为空​

大屏页面主标题用 JText​

装饰元素使用建议​

9. 数据集管理（动态数据源）​

数据集 API 端点​

组件绑定数据集​

10. 编辑与删除​

编辑已有大屏​

删除大屏​

11. 常见问题​