🌟 vue-large-screen-components

一个基于 Vue 3 + TypeScript + GSAP 的大屏可视化组件库，提供自动缩放容器、动态数字、文本、图表模板等通用组件，同时内置时间工具函数与动画插件，帮助你快速搭建炫酷的数据展示大屏。

✨ 特性

• 📏 自动缩放屏幕适配组件（ScaleScreen）
• 🔢 动态数字展示组件（Num / NumUnit）
• 🧾 通用文本与图表模板组件（Txt, ChartTemplate）
• ⏰ 内置时间工具函数：parseTime, getTime, getWeek
• 🎞️ 内置 GSAP 动画插件
• 🧩 一键全局注册，也可按需导入

📦 安装

npm install vue-large-screen-components
# 或使用 yarn / pnpm
yarn add vue-large-screen-components
pnpm add vue-large-screen-components

🚀 快速开始

在你的 Vue 3 项目中引入组件库。

全局注册

在 main.ts 中引入并注册组件库：

//main.ts
import { createApp } from 'vue'
import App from './App.vue'
import VueLargeScreenComponents from 'vue-large-screen-components'
import 'vue-large-screen-components/dist/style.css'

const app = createApp(App)
app.use(VueLargeScreenComponents)
app.mount('#app')

然后直接在模板中使用：

<template>
  <Num :value="12345.67" />
</template>

按需引入

如果只想使用某个组件，可以直接导入使用：

<template>
  <ScaleScreen>
    <Num :value="12345" />
  </ScaleScreen>
</template>

<script setup lang="ts">
import { ScaleScreen, Num } from 'vue-large-screen-components'
</script>

🧩 可用组件

| 组件名 | 说明 | 示例 | | --------------- | --------------- | ------------ | | ScaleScreen | 自动等比缩放容器组件 | 适配不同分辨率的大屏页面 | | Num | 动态数字动画组件 | 数值增长时平滑滚动 | | NumUnit | 带单位的动态数字组件 | 例如 “123 万台” | | Txt | 文本展示组件 | 支持样式配置与动画 | | ChartTemplate | 通用 ECharts 图表模板 | 支持自动渲染 |

🖥️ ScaleScreen 组件使用说明

<ScaleScreen> 是一个用于大屏自适应显示的容器组件，它可以根据设定的设计稿尺寸（如 1920×1080）自动进行等比缩放，保证在不同分辨率下页面内容完整展示。

使用示例

<template>
  <ScaleScreen :width="1920" :height="1080">
    <div class="dashboard">
      <h1>智慧城市大屏</h1>
    </div>
  </ScaleScreen>
</template>

<script setup lang="ts">
import { ScaleScreen } from 'vue-large-screen-components'
</script>

<style scoped>
.dashboard {
  width: 100%;
  height: 100%;
  color: #fff;
  background: linear-gradient(135deg, #002b45, #004b75);
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 40px;
}
</style>

Props 参数说明

| 参数名 | 类型 | 默认值 | 说明 | | -------------- | ----------------------------------------- | ------- | ----------------------- | | width | number \| string | 1920 | 设计稿宽度（基准宽度） | | height | number \| string | 1080 | 设计稿高度（基准高度） | | fullScreen | boolean | false | 是否独立按照宽高比例填充满屏幕（非等比） | | autoScale | boolean \| { x?: boolean, y?: boolean } | true | 是否启用自动缩放，可单独控制 x / y 方向 | | delay | number | 500 | 窗口变化后触发缩放的防抖延迟（毫秒） | | boxStyle | CSSProperties | {} | 外层容器样式（默认铺满全屏） | | wrapperStyle | CSSProperties | {} | 内层包裹内容样式 |

🔢 Num 数字滚动组件

用于展示动态数字，支持平滑过渡动画。

使用示例

<template>
  <Num :value="12345" />
</template>

Props 参数说明

| 属性名 | 类型 | 默认值 | 说明 | | ------------------------ | ------------------ | ----------- | ------------------- | | value | number \| string | 0 | 数字内容（基础传值方式） | | params.num | number | undefined | 数字内容（优先级高于 value） | | params.animateDuration | number | 0.5 | 动画持续时长（单位：秒） |

方法

| 方法名 | 说明 | | -------- | ------------------------- | | init() | 触发组件动画，可在父组件中通过 ref 调用。 |

🔢 NumUnit 数字+单位展示组件

用于同时展示数值、单位和可选前缀，带有平滑的过渡动画效果。
可通过 params 参数灵活控制动画时长、样式及显示内容。

使用示例

<template>
  <NumUnit
    :params="{
      numPre: '≈',
      num: 12345,
      unit: '台',
      animateDuration: 1.2,
      style: {
        numStyle: { color: '#00f', fontSize: '36px' },
        unitStyle: { color: '#999', marginLeft: '6px' }
      }
    }"
  />
</template>

Props 参数说明

| 参数 | 说明 | 类型 | 默认值 | | ---------------------- | -------------- | ------------------------ | ---- | | params.num | 数值内容 | number \| string | '' | | params.unit | 单位文本 | string | '' | | params.numPre | 前缀文本（如“≈”、“约”） | string | '' | | params.animateDuration | 动画时长（秒） | number | 1 | | params.style.numStyle | 数值样式 | Record<string, string> | {} | | params.style.unitStyle | 单位样式 | Record<string, string> | {} | | blockStyle | 外部传入的整体样式配置 | object | {} |

方法

| 方法名 | 说明 | | -------- | ------------------------- | | init() | 触发组件动画，可在父组件中通过 ref 调用。 |

🧾 Txt 动态文本组件

用于展示带动画效果的文本，支持打印机、扰乱、波浪等多种动画形式。

使用示例

<template>
  <Txt
    ref="txtRef"
    :value="'服务器运行正常'"
    :params="{
      animateType: 'waveSmall',
      animateDuration: 0.8
    }"
  />
</template>

Props 参数说明

| 参数 | 说明 | 类型 | 默认值 | | ---------------------- | ------------------------------------------------------ | --------------------- | ----- | | value | 显示文本内容 | string | '' | | params.text | 自定义文本（优先级高于 value） | string | '' | | params.animateDuration | 动画时长（秒） | number | 0.5 | | params.animateType | 动画类型，可选值：'print'、'scramble'、'wave'、'waveSmall' | 'waveSmall' | | | params.animateOpt | 自定义动画配置（GSAP 参数） | Record<string, any> | {} |

方法

| 方法名 | 说明 | | -------- | ------------------------- | | init() | 触发组件动画，可在父组件中通过 ref 调用。 |

📊 Chart 图表组件

基于 ECharts 封装的通用图表组件，支持动画淡入展示，可通过 init() 触发动画与初始化。

使用示例

<template>
  <Chart
    :option="chartOption"
    width="600"
    height="400"
    @getChartInstance="onGetChart"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import Chart from 'vue-large-screen-components/Chart.vue'

const chartOption = ref({
  title: { text: '销售趋势' },
  tooltip: {},
  xAxis: { data: ['1月', '2月', '3月', '4月'] },
  yAxis: {},
  series: [
    {
      name: '销量',
      type: 'bar',
      data: [5, 20, 36, 10]
    }
  ]
})

const onGetChart = (chartInstance) => {
  console.log('ECharts 实例:', chartInstance)
}
</script>

Props参数说明

| 参数 | 说明 | 类型 | 默认值 | | ------ | ---------------- | ------------------ | -------- | | option | ECharts 图表配置项 | object | {} | | width | 图表宽度，支持数字或百分比字符串 | number \| string | '100%' | | height | 图表高度，支持数字或百分比字符串 | number \| string | '100%' |

事件

| 事件名 | 说明 | 回调参数 | | ---------------- | ----------- | -------------------------- | | getChartInstance | 图表实例创建完成时触发 | (chart: echarts.ECharts) |

方法

| 方法名 | 说明 | | -------- | ----------------------- | | init() | 触发图表淡入动画并初始化 ECharts 实例 |

🎬 动画组件使用说明（重要）

部分组件（如 Num、NumUnit、Txt、ChartTemplate）带有动画效果，动画默认不会自动播放。 如果希望动画生效，需要手动调用组件的 init() 方法。

<template>
  <div>
    <Num ref="numRef" :value="1234" />
    <Txt ref="txtRef" value="系统运行中..." />
    <Chart ref="chartRef" :option="option" width="500" height="300" />
    <button @click="playAnimation">播放动画</button>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { Num, Txt, Chart } from 'vue-large-screen-components'

const numRef = ref()
const txtRef = ref()
const chartRef = ref()

const option = {
  xAxis: { data: ['A', 'B', 'C'] },
  yAxis: {},
  series: [{ type: 'bar', data: [10, 20, 30] }]
}

const playAnimation = () => {
  numRef.value?.init()
  txtRef.value?.init()
  chartRef.value?.init()
}

// 页面加载时自动播放
onMounted(() => {
  playAnimation()
})
</script>

💡 提示：

组件内部均基于 GSAP动画库构建。

可在组件加载后（onMounted）或交互事件中触发动画。

init() 方法可多次调用，支持重新播放动画。

🧰 工具函数

| 函数名 | 功能说明 | | ----------- | ----------- | | parseTime | 格式化时间字符串 | | getTime | 获取当前时间（时分秒） | | getWeek | 获取当前星期 |

parseTime(time, format?)

格式化时间对象/时间戳/时间字符串

import { parseTime } from 'vue-large-screen-components'

// 默认格式
parseTime(new Date()) // "2023-08-15 14:30:45"

// 自定义格式
parseTime(1692081045000, '{y}年{m}月{d}日 {h}时{i}分') // "2023年08月15日 14时30分"

import { getTime } from 'vue-large-screen-components'

getTime() // "2023-08-15 14:30:45"
getTime('/', '|') // "2023/08/15 14|30|45"

import { getWeek } from 'vue-large-screen-components'

getWeek() // "二" (表示星期二)