@kxliu/dvc-ui

@kxliu/dvc-ui

数据大屏（Data Visualization Container）组件库。以 1920 × 1080 为默认设计稿基准，内容按设计稿 px 尺寸开发，容器自动等比例缩放适配任意屏幕，无需为每种分辨率单独调试。

基于 Vue 3 + TypeScript，零运行时依赖（vue 为 peerDependency）。

特性

• 默认 1920×1080：与常见大屏设计稿基准一致，直接还原设计稿
• 自动等比例缩放：ResizeObserver 监听容器尺寸，等比缩放并居中，窗口变化实时适配
• 自定义背景：支持背景颜色、背景图片及尺寸 / 重复 / 定位配置
• 多缩放模式：uniform（等比）/ stretch（铺满拉伸）/ none（原始尺寸），或手动指定比例
• 全屏能力：容器提供全屏方法，父级可直接调用，插槽内的子模块也可注入后调用
• TypeScript：全量类型定义，支持组件与 useScreenScale 组合式 API

安装

npm install @kxliu/dvc-ui
# yarn add @kxliu/dvc-ui
# pnpm add @kxliu/dvc-ui

快速开始

引入组件与样式后即可使用：

<script setup lang="ts">
import { DvScreen } from '@kxliu/dvc-ui'
import '@kxliu/dvc-ui/dist/style.css'
</script>

<template>
  <!-- 外层父容器需要有明确宽高，如 100vw / 100vh -->
  <div class="screen-wrapper">
    <DvScreen>
      <!-- 内部一律按 1920 * 1080 设计稿尺寸写死像素 -->
      <div class="board">安全生产监测大屏</div>
    </DvScreen>
  </div>
</template>

<style>
.screen-wrapper {
  width: 100vw;
  height: 100vh;
}

.board {
  width: 1920px;
  height: 1080px;
  font-size: 48px;
}
</style>

注意：DvScreen 的外层父容器需要有明确宽高（如 100vw / 100vh），否则无法计算缩放比例。样式文件通过 import '@kxliu/dvc-ui/dist/style.css' 引入，建议在应用入口处引用一次。

组件

DvScreen 大屏容器

默认插槽内容按 width × height 的固定设计稿尺寸渲染，外层容器自动等比缩放居中。

<template>
  <DvScreen :width="1920" :height="1080" bg-color="#0b1e3f" bg-image="/bg.png">
    <YourDashboard />
  </DvScreen>
</template>

API

Events

Methods

通过组件实例（ref）调用：

<script setup lang="ts">
import { DvScreen } from '@kxliu/dvc-ui'

const screen = ref<InstanceType<typeof DvScreen>>()
const onToggle = () => screen.value?.toggleFullscreen()
</script>

<template>
  <DvScreen ref="screen" @fullscreen-change="(v) => console.log('fullscreen:', v)">
    <YourDashboard />
  </DvScreen>
</template>

Slots

子模块调用全屏

插槽内的子模块（面板、图表卡片等）通过 useScreenFullscreen() 注入外层容器的全屏能力， 即可让子模块自身控制整个大屏的全屏 / 退出全屏：

<script setup lang="ts">
import { useScreenFullscreen } from '@kxliu/dvc-ui'

// 必须在 DvScreen 插槽内调用
const { isFullscreen, toggle } = useScreenFullscreen()
</script>

<template>
  <button @click="toggle()">{{ isFullscreen ? '退出全屏' : '全屏' }}</button>
</template>

原生 Fullscreen API 不可用或被拒绝时（如页面嵌在未授权 allowfullscreen 的 iframe 内）， 会自动降级为容器固定定位铺满视口，保证全屏按钮始终可用。

useScreenScale

可脱离组件单独使用的组合式 API，返回 Ref<{ x, y }> 缩放比例。

import { useScreenScale } from '@kxliu/dvc-ui'

const root = ref<HTMLElement | null>(null)
const scale = useScreenScale(root, () => ({ width: 1920, height: 1080 }))
// scale.value.x / scale.value.y

useScreenFullscreen

在 DvScreen 插槽内的子模块中调用，获取外层容器的全屏能力，返回 { isFullscreen, fallback, supported, enter, exit, toggle }：

import { useScreenFullscreen } from '@kxliu/dvc-ui'

// 需在 DvScreen 插槽内调用
const { isFullscreen, supported, enter, exit, toggle } = useScreenFullscreen()

DvHeaderNavy 深蓝科技风头部

深蓝科技风大屏头部，高度 80px，三栏布局：标题 / 左对齐导航（超出收纳进「更多」）/ 主页、清屏、全屏图标与实时时钟。

<script setup lang="ts">
import { DvScreen, DvHeaderNavy } from '@kxliu/dvc-ui'

const nav = [
  { label: '运营总览', key: 'overview' },
  { label: '综合治理', key: 'govern' },
]
</script>

<template>
  <DvScreen bg-color="#030a1c">
    <DvHeaderNavy title="深蓝科技风可视化数据大屏" :nav="nav" active="govern" />
    <!-- 业务内容 -->
  </DvScreen>
</template>

API

DvHeaderNavyNavItem：{ label: string; key?: string; disabled?: boolean }

Events

全屏图标置于 DvScreen 内时控制整个大屏；单独使用时全屏当前页面。

DvHeaderSafety 流动光效头部

左侧粗体渐变标题，中部斜切导航，右侧为 #extra 信息位、主页 / 清屏 / 全屏图标与时钟；底部为流光轨道。

<DvScreen bg-color="#0A1428">
  <DvHeaderSafety title="安全生产监管平台" :nav="nav" v-model:active="active" theme="techBlue" />
</DvScreen>

插槽：title、extra（图标左侧，最宽 360px，不裁剪溢出）。事件：nav-click、home、clear(cleared)、fullscreen-toggle(fullscreen)。

主题预设（theme，只设置背景与主色，其余发光、边框、高亮色自动推断）：techBlue 科技蓝（默认）、commandBlue 指挥蓝、iceCyan 冰青、deepPurple 暗夜紫、cyberCyan 赛博青、ecoGreen 生态绿、matrixGreen 矩阵绿、financeBlue 金融蓝、redGold 红金、neonPink 霓虹粉。也可以通过 dvThemePresets 获取完整列表。

字体

大屏主标题（DvHeaderNavy、DvHeaderSafety）使用 阿里妈妈数黑体（Alimama ShuHeiTi），随包发布子集化的 woff2（dist/fonts/alimama-shuheiti-subset.woff2，约 677KB）。

• 子集范围：GB2312 全部汉字、ASCII 字母数字与常用中文标点。范围外的字符会回退到苹方 / 微软雅黑。
• 版权：阿里巴巴（中国）有限公司，版本 1.005（beta）。使用协议以阿里妈妈官方声明为准（https://fonts.alibabagroup.com/）：可用于商业用途，不得单独出售字体文件，不得作为商标或 logo 字，不得二次创作。
• DvHeaderGold 的牌匾标题保留宋体系字体，不使用数黑体。

大屏表单组件

DvTreeSelect 树形下拉筛选

大屏风格的树形下拉，单选，任意层级节点均可选中，适用于行政区划、组织架构等筛选。支持搜索过滤、自定义字段名、显示完整路径。

<script setup lang="ts">
import { ref } from 'vue'
import { DvTreeSelect } from '@kxliu/dvc-ui'

// 接口字段为 name / code / sub 时，用 field-names 直接映射
const regions = [{ name: '浙江省', code: 33, sub: [{ name: '杭州市', code: 3301 }] }]
const value = ref<string | number | null>(3301)
</script>

<template>
  <DvTreeSelect v-model="value" :options="regions" :field-names="{ label: 'name', value: 'code', children: 'sub' }" show-path />
</template>

事件：update:modelValue、change(value, node, path)、clear、visible-change(open)。

下拉面板就地渲染（随 DvScreen 一起缩放），若祖先元素设置了 overflow: hidden 会裁剪面板；暂不含虚拟滚动，节点数过万请分级加载。

DvInput 文本框

大屏搜索条用文本框，支持可清除、最大长度、前后缀插槽；回车触发 search。

<DvInput v-model="keyword" placeholder="设备名称" :width="180" @search="onSearch" />

插槽：prefix、suffix。事件：update:modelValue、change(value)、search(value)、clear。

DvSelect 下拉框

单选下拉，扁平选项，支持搜索（命中高亮）、禁用项、自定义字段名。

<DvSelect v-model="status" :options="[{ label: '正常', value: 'run' }, { label: '告警', value: 'warn', disabled: true }]" />

事件：update:modelValue、change(value, option)、clear、visible-change(open)。

DvDatePicker 日期框

支持单日期、月、年以及范围选择，只使用原生 Date。值为字符串：日 YYYY-MM-DD、月 YYYY-MM、年 YYYY；范围为两个字符串组成的数组。

<DvDatePicker v-model="day" />                         <!-- 2026-10-14 -->
<DvDatePicker v-model="month" type="month" />          <!-- 2026-10 -->
<DvDatePicker v-model="range" range min="2026-01-01" max="2026-12-31" />  <!-- ['2026-10-01', '2026-10-20'] -->

范围选择：先点开始日期，面板顶部提示「→ 请选择结束」，再点结束日期完成；结束早于开始会自动交换。「今天」按钮仅在单日期模式下显示。事件：update:modelValue、change(value)、clear、visible-change(open)。

DvSearchBar 搜索条

横排容器，表单项放在默认插槽里，右侧为「查询」「重置」。容器不持有表单值，重置时需在 reset 事件中自行清空。

<DvSearchBar @search="query" @reset="clearForm">
  <DvInput v-model="keyword" :width="160" />
  <DvSelect v-model="status" :options="statusOptions" :width="140" />
  <DvDatePicker v-model="range" range :width="240" />
</DvSearchBar>

事件：search（点击查询，或在表单项内回车；打开下拉的回车不触发）、reset。

表单类组件的下拉面板同样是就地渲染，随 DvScreen 缩放，祖先元素的 overflow: hidden 会裁剪面板。

生态与约定

• 内部图表、表格等子组件同样按设计稿 px 开发，放置于 DvScreen 内即随大屏一起缩放
• 使用 ECharts 等 canvas 类库时，可通过 scale-change 事件或 useScreenScale 同步触发实例 resize

本地开发

# 仓库根目录
npm install
npm run dev      # 启动文档站
npm run build    # 构建组件库 + 文档站

发布

npm run publish:lib

License

MIT