@leaf-screen/ui

Leaf Screen UI

面向数据大屏的 Vue 3 组件库，使用 TypeScript、Tailwind CSS 4、ECharts 5 和少量兼容性 SCSS 构建。组件不依赖接口、状态管理或 UI 框架，可以按需组合到业务大屏中。

开发文档与快速开始

• 快速开始：环境要求、安装与可直接使用的 App.vue 示例。
• 安装与下载：pnpm / npm / Yarn、指定版本与 .tgz 包下载。
• 组件使用：按需引用、全量注册和项目级图表配置。
• 大屏开发与布局：跟着城市运行中心 Demo 理解组件分工、三栏布局、数据联动并复制完整页面。
• 版本历史：组件包版本与更新记录。

安装

pnpm add @leaf-screen/ui echarts vue

需要 Vue ^3.5.0、ECharts ^5.5.1 和支持 ESM 的 Vue 构建环境。vue 和 echarts 是 peer dependencies，需要由使用方项目提供。无需额外安装 Tailwind CSS 或 SCSS。npm / Yarn 用户可使用：

npm install @leaf-screen/ui echarts@^5.5.1 vue@^3.5.0
# 或
yarn add @leaf-screen/ui echarts@^5.5.1 vue@^3.5.0

下载当前发布包：npm pack @leaf-screen/ui@0.3.0。按需引用与全量注册均需引入样式，在项目入口引入一次即可：

import '@leaf-screen/ui/style.css'

全量注册

import { createApp } from 'vue'
import LeafScreenUi from '@leaf-screen/ui'
import '@leaf-screen/ui/style.css'
import App from './App.vue'

createApp(App)
  .use(LeafScreenUi)
  .mount('#app')

按需使用

在 Vue 单文件组件的 <script setup> 中具名导入即可，无需额外注册：

<script setup lang="ts">
import { ScreenCard } from '@leaf-screen/ui'
import '@leaf-screen/ui/style.css'
</script>

<template>
  <ScreenCard title="运行状态" height="240px">
    <p>设备运行正常</p>
  </ScreenCard>
</template>

项目级图表文字

统一 textStyle 在项目入口配置一次，不需要在每个 option 中重复声明：

import { createApp } from 'vue'
import { configureCharts } from '@leaf-screen/ui'
import App from './App.vue'

const app = createApp(App)
configureCharts(app, {
  textStyle: { color: '#b8ced9', fontFamily: 'Microsoft YaHei, sans-serif', fontSize: 12 },
})
app.mount('#app')

图表继承项目默认值，确有差异时可用局部文字样式覆盖。不同 Vue 应用的配置彼此独立。

数据、颜色与系列

业务数据、调色数组和多系列名称分别声明，grid、标签角度与轮播间隔通过 Props 传入：

<script setup>
import { ScreenPrismBarChart } from '@leaf-screen/ui'

const chartData = [
  { name: '东部智能制造园区', value: [68, 52] },
  { name: '南部数字产业园区', value: [92, 71] },
]
const colors = ['#34d5ed', '#ffc857']
const seriesNames = ['本期', '同期']
const grid = { bottom: 24, containLabel: true }
</script>

<template>
  <ScreenPrismBarChart
    :height="360"
    :data="chartData"
    :color="colors"
    :series-names="seriesNames"
    :grid="grid"
    :x-axis-label-rotate="30"
    :y-axis-label-rotate="0"
    :auto-tooltip="true"
  />
</template>

角度单位为度，0 表示不倾斜；多轴可使用数组，例如 :y-axis-label-rotate="[0, 30]"。grid 覆盖会保留未指定的默认边距，多网格可传数组。

autoTooltip 控制提示轮播，间隔使用 autoTooltipInterval（默认 3000ms）；轴提示会同时高亮同一分类的系列，鼠标进入后暂停，移出后恢复。

非地图立体图表

这些组件使用 ECharts Canvas 投影表现厚度，不需要 echarts-gl，也不提供三维视角旋转：

• ScreenPrismBarChart：shape 支持 prism（棱柱）、cylinder（圆柱）、bevel（斜切高光柱）；horizontal 切换横向布局，stacked 按 value 数组顺序堆叠，segments 增加柱身视觉分节（不改变数值）。负值与无效值按 0 处理。
• Screen3DDonutChart：innerRadius="0" 为实心饼图；roseType="radius" 随业务量改变扇区半径，exploded 将扇区外移，surfaceStyle="glass" 设置半透明顶面。实心饼图自动隐藏环心指标。
• Screen3DRingChart：各分类占一条同心轨道，标量 value 为百分比，数组 value 为 [实际, 目标]；seriesNames 对应这两个指标。中心为各分类达成率的算术平均，超额进度最多绘制一圈，提示仍显示真实达成率。非正数目标对应 0% 达成率。

<script setup>
import { Screen3DRingChart } from '@leaf-screen/ui'

const chartData = [
  { name: '生产', value: [86, 100] },
  { name: '交付', value: [72, 90] },
  { name: '质检', value: [94, 100] },
]
const colors = ['#34d5ed', '#ffc857', '#65e6ab']
const seriesNames = ['实际', '目标']
</script>

<template>
  <Screen3DRingChart
    :height="360"
    :data="chartData"
    :color="colors"
    :series-names="seriesNames"
    title="平均达成率"
    unit="万件"
    :auto-tooltip="true"
    :auto-tooltip-interval="2500"
  />
</template>

<script setup lang="ts">
import { ScreenCard, ScreenContainer, ScreenLineChart } from '@leaf-screen/ui'

const trendData = [
  { name: '08', value: [42, 36] },
  { name: '09', value: [68, 54] },
  { name: '10', value: [57, 61] },
  { name: '11', value: [81, 70] },
  { name: '12', value: [76, 71] },
]
</script>

<template>
  <ScreenContainer :width="1920" :height="1080" fit="contain">
    <ScreenCard title="事件趋势" height="360px">
      <ScreenLineChart :data="trendData" :series-names="['受理量', '办结量']" />
    </ScreenCard>
  </ScreenContainer>
</template>

预设图表直接接收后端常见的 { name, value } 数据，value 可以是数字、数字字符串或数值数组：

• ScreenLineChart：数组值自动生成多条折线，使用 series-names 指定系列名称。
• ScreenBarChart：数组值自动生成多组柱状图，color 支持纯色或渐变对象，传数组时按系列顺序取用。
• ScreenPieChart：使用 series-index 指定 value 数组中的维度，默认为 0。

玫瑰图可用 rose、rose-type（radius / area）与 rose-scale（linear / sqrt）调整；开启 sqrt 会自动改用 area 模式并按原始数值重算标签与 tooltip 百分比。

自定义图表

需要雷达图、地图、双轴、dataZoom 或任意 ECharts 配置时，直接使用 ScreenChart：

<script setup lang="ts">
import type { EChartsOption } from 'echarts'
import { ScreenChart } from '@leaf-screen/ui'

const chartData = [{ name: '当前表现', value: [86] }]
const option: EChartsOption = {
  radar: { indicator: [{ name: '响应', max: 100 }] },
  series: [{ type: 'radar', data: chartData }],
}
</script>

<template>
  <ScreenChart :option="option" style="height: 320px" />
</template>

定时刷新

数据每分钟推送时不会打断正在播放的动画：ScreenRankingBar 只在行数或布局变化时复位滚动位置；ScreenCustomLegendPieChart 的数据刷新后按分类名找回高亮项。

卡片与页头

ScreenCard 默认使用内置的蓝色标题框素材，可通过 title-background 覆盖为任意 CSS 背景值：

<ScreenCard
  title="重点资源实时运行状态与应急保障情况"
  background="rgba(0, 44, 97, 0.8)"
  title-background="linear-gradient(90deg, #0053bb, #00336f)"
  :title-font-size="24"
  :title-min-font-size="16"
  height="360px"
>
  <!-- 内容 -->
</ScreenCard>

卡片内容区域默认透明；标题会按可用宽度自动缩放，最小 16px，可用 title-font-size、title-min-font-size、auto-fit-title 调整。

ScreenHeader 默认固定在大屏容器顶部，普通文档流场景可设置 :fixed="false"，右侧默认显示日期、时间和星期：

<ScreenHeader
  title="城市运行指挥中心"
  title-align="content"
  :title-font-size="40"
  :title-min-font-size="18"
/>

宽肩地图布局

ScreenMapLayout 以 ScreenShoulderLayout 为基础，左右区域独立滚动，中间区域优先用于地图。桌面端三栏并列，小于 1100px 后按地图、左栏、右栏顺序堆叠：

<ScreenMapLayout
  height="100dvh"
  left-width="clamp(270px, 20vw, 350px)"
  right-width="clamp(280px, 22vw, 400px)"
  gap="24px"
  padding="16px 24px 24px"
>
  <template #header>
    <ScreenHeader title="城市运行指挥中心" title-align="content" />
  </template>
  <template #left><!-- 左侧指标 --></template>
  <template #map>
    <ScreenGeoMap :geo-json="geoJson" :data="districtData" />
  </template>
  <template #right><!-- 右侧趋势 --></template>
</ScreenMapLayout>

自适应画布

ScreenContainer 是大屏根容器，默认将固定的 1920 × 1080 画布按比例缩放到可用区域：

页面不需要固定画布时设置 :auto-fit="false"。

地图交互（可选）

useMapMask 适配高德 JSAPI，提供城市外遮罩、区域多边形、区域旗子、hover 信息窗与点击下钻，业务数据与文案全部从 options 注入；useMapScaleCompensate 用于抵消屏幕容器的 transform: scale()，避免地图交互与气泡定位偏移。

内置素材

assets/map 下的点位图标已从入口导出：

import { mapMarkerDefault, mapMarkerRepair, mapArrowLeft } from '@leaf-screen/ui'

new AMap.Marker({
  position: [116.4, 39.9],
  content: ``,
})

组件一览

• 布局：ScreenContainer、ScreenCard、ScreenHeader、ScreenTitle、ScreenShoulderLayout、ScreenMapLayout、ScreenMetricGrid
• 导航与展示：ScreenTabs、ScreenTime、ScreenNumber、ScreenNumberItem、ScreenAnimateNumber、ScreenCardIcon、ScreenMarquee、ScreenCarousel、ScreenRankingBar
• 图表：ScreenChart、ScreenBarChart、ScreenLineChart、ScreenPieChart、ScreenCustomLegendPieChart、ScreenGeoMap 等
• Composables：useScreenFit、useECharts、useCountUp、useAutoFitText、useRegionCarousel、useMapMask、useMapScaleCompensate
• 工具：formatNumber、formatDate、formatWeekday、resolveKeepVisibleScrollTop、resolveActiveIndexByName