@hz_yujin/vue-screen

Vue 3 数据大屏适配与布局组件。

• ProScreenAdapter — 设计稿缩放容器（默认 stretch 撑满）
• ProScreenHeader — 大屏页头（标题 / 副标题 / 左右插槽）
• ProScreenGrid / ProScreenGridItem — 24 栏栅格
• ProBizCard — 大屏业务卡片外壳

安装

npm install @hz_yujin/vue-screen vue

vue 为 peerDependencies，需由宿主项目安装。

使用

import { createApp } from 'vue'
import {
  ProScreenAdapter,
  ProScreenHeader,
  ProScreenGrid,
  ProScreenGridItem,
  ProBizCard,
} from '@hz_yujin/vue-screen'
import '@hz_yujin/vue-screen/style.css'

// 或全局注册
import VueScreen from '@hz_yujin/vue-screen'
app.use(VueScreen)

<template>
  <ProScreenAdapter
    theme="black"
    title="运营数据大屏"
    subtitle="Demo"
    :design-width="1920"
    :design-height="1080"
    :columns="4"
    :gap="16"
  >
    <ProBizCard title="面板 1">内容</ProBizCard>
    <ProBizCard title="面板 2">内容</ProBizCard>
    <ProBizCard title="面板 3">内容</ProBizCard>
    <ProBizCard title="面板 4">内容</ProBizCard>
  </ProScreenAdapter>
</template>

自定义复杂布局时关闭内置栅格：

<ProScreenAdapter :grid="false" title="自定义布局">
  <ProScreenGrid :cols="24" :gap="16">
    <ProScreenGridItem :span="8">...</ProScreenGridItem>
    <ProScreenGridItem :span="16">...</ProScreenGridItem>
  </ProScreenGrid>
</ProScreenAdapter>

ProScreenAdapter

设计稿缩放根容器。负责按 designWidth × designHeight 适配视口、渲染页头、内置栅格，以及全屏 / 样式设置入口。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | theme | 'blue' \| 'black' \| 'white' | 'black' | 内置主题。会同步页头、全屏按钮与嵌套 ProBizCard 的默认配色；单独传入的颜色类 props 仍可覆盖对应项 | | designWidth | number | 1920 | 设计稿宽度（px），缩放以此为基准 | | designHeight | number | 1080 | 设计稿高度（px），缩放以此为基准 | | background | string | 跟随 theme | 留边 / 容器背景色，支持纯色、rgba、渐变等 CSS 背景值 | | fitMode | 'stretch' \| 'contain' \| 'cover' \| 'width' \| 'height' | 'stretch' | 设计稿填充模式，见下方说明 | | verticalAlign | 'top' \| 'center' | 'top' | 设计稿垂直对齐；仅在 contain / width 模式下生效（top 贴顶，center 垂直居中） | | title | string | '' | 页头主标题；有值时自动渲染内置 ProScreenHeader | | subtitle | string | '' | 页头副标题 | | headerHeight | number \| string | 72 | 页头高度；数字按 px 处理，也可传 '80px' 等 CSS 长度 | | headerBackground | string | 跟随 theme | 页头背景，支持纯色或渐变 | | titleColor | string | 跟随 theme | 主标题文字颜色 | | titleSize | number \| string | 34 | 主标题字号；数字按 px 处理 | | subtitleColor | string | 跟随 theme | 副标题文字颜色 | | subtitleSize | number \| string | 14 | 副标题字号；数字按 px 处理 | | showHeader | boolean | 自动 | 是否显示页头。未传时：有 title / subtitle / 页头相关插槽则显示；传 false 可强制隐藏 | | showTime | boolean | true | 是否在页头左上角显示当前时间 | | showFullscreenBtn | boolean | true | 是否显示右上角「全屏 / 退出全屏」按钮 | | showSettingsBtn | boolean | true | 是否显示右上角样式设置（齿轮）按钮；打开后可编辑样式并写入 localStorage | | fullscreenBtnColor | string | 跟随 theme | 全屏按钮图标颜色 | | fullscreenBtnBg | string | 跟随 theme | 全屏按钮背景色 | | grid | boolean | true | 是否启用内置栅格。为 true 时，default 插槽的每个根节点自动作为一格；为 false 时可自行组合 ProScreenGrid | | columns | number | 4 | 内置栅格每行等分列数（如 4 表示一行四个） | | cols | number | 24 | 内置栅格总列数（传给底层栅格系统） | | gap | number \| string | 16 | 内置栅格间距；数字按 px 处理 |

theme 主题

| 值 | 说明 | |----|------| | black（默认） | 炭黑管理台风 | | blue | 深蓝科技风 | | white | 浅色背景 |

主题会同步页头、全屏按钮与嵌套的 ProBizCard 配色；单独传入的 background / headerBackground / titleColor 等仍可覆盖对应项。

fitMode 填充模式

| 值 | 说明 | |----|------| | stretch（默认） | 宽高独立缩放，始终撑满容器（可能轻微变形） | | contain | 等比缩放完整显示，可能留白 | | cover | 等比铺满，可能裁切 | | width | 按宽度等比缩放 | | height | 按高度等比缩放 |

样式设置抽屉

• 右上角齿轮按钮（showSettingsBtn，默认 true）打开右侧抽屉
• 可编辑 Adapter / BizCard 常用样式属性，自动写入 localStorage，刷新后保留
• 抽屉内「重置」可清除本地缓存并恢复为当前 props / 主题默认值
• 可用 :show-settings-btn="false" 隐藏

事件

| 事件名 | 参数 | 说明 | |--------|------|------| | fullscreenChange | (value: boolean) | 全屏状态变化时触发 |

插槽

| 插槽名 | 说明 | |--------|------| | default | 大屏主体内容；grid=true 时每个根节点自动成格 | | header | 整块自定义页头（替换内置页头） | | header-left | 页头左侧区域（与 showTime 共存时一并渲染） | | header-right | 页头右侧区域 | | header-title | 自定义主标题内容 | | header-subtitle | 自定义副标题内容 |

暴露方法 / 属性（ref）

| 名称 | 类型 | 说明 | |------|------|------| | scale | Ref<number> | 当前统一缩放比（部分模式下有意义） | | scaleX | Ref<number> | 横向缩放比 | | scaleY | Ref<number> | 纵向缩放比 | | isFullscreen | Ref<boolean> | 是否处于全屏 | | update | () => void | 手动触发一次尺寸重算 | | enterFullscreen | () => Promise<void> | 进入全屏 | | exitFullscreen | () => Promise<void> | 退出全屏 | | toggleFullscreen | () => Promise<void> | 切换全屏 |

内置栅格行为

默认 grid=true，会将 default 插槽的每个根节点自动包成一格：

| Prop | 说明 | 默认 | |------|------|------| | grid | 是否启用内置栅格 | true | | columns | 每行等分列数 | 4 | | cols | 栅格总列数 | 24 | | gap | 栅格间距 | 16 |

行数由子节点数量自动换行，行高均分（例如 8 个子节点 + columns=4 → 两行）。需要不等宽 / 跨列布局时设 :grid="false"，再自行使用 ProScreenGrid / ProScreenGridItem。

ProScreenHeader

可单独使用的大屏页头；在 ProScreenAdapter 中传入 title / subtitle 时也会自动渲染。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | title | string | '' | 主标题文案 | | subtitle | string | '' | 副标题 / 描述文案 | | height | number \| string | 72 | 页头高度；数字按 px 处理 | | background | string | 青蓝横向渐变 | 页头背景，支持纯色或渐变 | | titleColor | string | '#eaf4ff' | 主标题颜色 | | titleSize | number \| string | 34 | 主标题字号；数字按 px 处理 | | subtitleColor | string | 'rgba(158, 201, 255, 0.72)' | 副标题颜色 | | subtitleSize | number \| string | 14 | 副标题字号；数字按 px 处理 |

插槽

| 插槽名 | 说明 | |--------|------| | left | 左侧区域 | | right | 右侧区域 | | title | 自定义主标题（覆盖 title prop） | | subtitle | 自定义副标题（覆盖 subtitle prop） |

ProScreenGrid

24 栏栅格容器，需配合 ProScreenGridItem 使用。通常在 ProScreenAdapter 设 :grid="false" 后自行布局。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | cols | number | 24 | 栅格总列数 | | gap | number \| string | 16 | 格子间距；数字按 px 处理 |

插槽

| 插槽名 | 说明 | |--------|------| | default | 放置若干 ProScreenGridItem |

ProScreenGridItem

栅格单元。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | span | number | 24 | 占据列数（相对父级 cols） | | offset | number | 0 | 左侧偏移列数 | | rowSpan | number | 1 | 跨行数 |

插槽

| 插槽名 | 说明 | |--------|------| | default | 格子内容 |

ProBizCard

大屏业务卡片外壳。嵌套在 ProScreenAdapter 内时，未传的颜色 / 阴影等会跟随 Adapter 的 theme（及样式设置抽屉中的 Card 配置）。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | title | string | '' | 卡片标题；有值或存在 title 插槽时显示头部 | | background | string | 跟随 theme / #101010 | 卡片背景色 | | headerBackground | string | 跟随 theme | 头部背景色，支持纯色或渐变 | | headerHeight | number \| string | 42 | 头部高度；数字按 px 处理 | | titleColor | string | 跟随 theme | 标题文字颜色 | | titleSize | number \| string | 16 | 标题字号；数字按 px 处理 | | borderColor | string | 跟随 theme | 边框颜色 | | borderRadius | number \| string | 6 | 圆角；数字按 px 处理 | | boxShadow | string | 跟随 theme | 完整 CSS box-shadow 值 | | hoverShadow | boolean | true（单独使用时以组件默认为准） | 鼠标悬停时是否显示增强阴影 | | showFullscreenBtn | boolean | true | 是否显示标题栏右上角「全屏 / 退出全屏」图标按钮 |

单独使用（不在 Adapter 内）时，未传颜色类 props 会回落到组件内置深色默认值。

卡片全屏为铺满视口的浮层（非浏览器 Fullscreen API），Esc 或再次点击图标可退出。

事件

| 事件名 | 参数 | 说明 | |--------|------|------| | fullscreenChange | (value: boolean) | 卡片全屏状态变化时触发 |

插槽

| 插槽名 | 说明 | |--------|------| | default | 卡片主体内容 | | title | 自定义标题区域（覆盖 title prop 文案） | | extra | 标题栏右侧扩展区（全屏按钮左侧） |

完整示例（常用 Props）

<template>
  <ProScreenAdapter
    theme="black"
    title="运营数据大屏"
    subtitle="实时业务监控"
    :design-width="1920"
    :design-height="1080"
    background="#0f0f0f"
    header-background="#141414"
    :header-height="72"
    title-color="#ffffff"
    :title-size="34"
    subtitle-color="rgba(153, 153, 153, 0.95)"
    :subtitle-size="14"
    :show-header="true"
    :show-time="true"
    :show-fullscreen-btn="true"
    :show-settings-btn="true"
    fullscreen-btn-color="#ffffff"
    fullscreen-btn-bg="#2d8cf0"
    fit-mode="stretch"
    vertical-align="top"
    :grid="true"
    :columns="4"
    :cols="24"
    :gap="16"
  >
    <ProBizCard
      title="访问趋势"
      background="#101010"
      header-background="#1a1a1a"
      :header-height="42"
      title-color="#ffffff"
      :title-size="16"
      border-color="#2a2a2a"
      :border-radius="6"
      box-shadow="none"
      :hover-shadow="true"
    >
      图表等内容
    </ProBizCard>
  </ProScreenAdapter>
</template>