yl-big-screen

yl-big-screen

大屏可视化通用 Vue 3 组件库。提供大屏项目的标准布局、自适应缩放、面板容器和弹窗系统。

快速开始

# pnpm
pnpm install yl-big-screen

# 或 npm
npm install yl-big-screen

// main.ts —— 无需手动引入样式，组件会自动注入
import { createApp } from "vue";
import App from "./App.vue";

createApp(App).mount("#app");

<!-- App.vue -->
<script setup>
import { ProjectScreenRoot, ProjectPanelShell, openBigScreenDialog } from "yl-big-screen";
</script>

<template>
  <ProjectScreenRoot title="我的大屏">
    <template #header-left>
      <span>2026-05-28</span>
    </template>

    <div style="display: grid; grid-template-columns: 400px 1fr 400px; gap: 16px; height: 100%;">
      <ProjectPanelShell title="左侧面板">
        <p>内容...</p>
      </ProjectPanelShell>
      <ProjectPanelShell title="中间面板">
        <p>内容...</p>
      </ProjectPanelShell>
      <ProjectPanelShell title="右侧面板">
        <p>内容...</p>
      </ProjectPanelShell>
    </div>
  </ProjectScreenRoot>
</template>

组件 API

ProjectScreenRoot

大屏根布局组件，包含自适应缩放、顶部标题栏、内容区和弹窗容器。

Props

Slots

ScreenState 类型

{
  containerWidth: number   // 实际容器宽度
  containerHeight: number  // 实际容器高度
  contentWidth: number     // 内容宽度
  contentHeight: number    // 内容高度
  scale: number            // 最小缩放比
  scaleX: number           // X 轴缩放比
  scaleY: number           // Y 轴缩放比
  offsetX: number          // X 轴偏移
  offsetY: number          // Y 轴偏移
}

Events

Expose

使用示例

<ProjectScreenRoot
  title="智慧城市大屏"
  :width="1920"
  :height="1080"
  scale-mode="fixed-height"
  @title-click="handleTitleClick"
  @scale-update="handleScaleUpdate"
>
  <template #header-left>
    <span>2026-05-28 12:00:00</span>
  </template>
  <template #header-right>
    <button @click="openDialog">菜单</button>
  </template>

  <!-- 默认插槽放主内容 -->
  <div class="my-charts">...</div>
</ProjectScreenRoot>

ProjectScreenScale

自适应缩放容器组件。ProjectScreenRoot 底层使用的就是它，也可以独立使用。

Props（与 ProjectScreenRoot 的缩放相关属性完全一致）

Slots

Events: @update — 缩放状态更新，参数同 ScreenState

Expose: refresh() — 手动触发缩放重算

使用示例

<ProjectScreenScale :width="1920" :height="1080" mode="fixed-height">
  <div class="my-fixed-size-content">
    <!-- 这里的内容会按 1920x1080 缩放适配 -->
  </div>
</ProjectScreenScale>

ProjectPanelShell

面板容器组件，标题条浮动在面板上方，带有装饰边框。

Props

Slots

Events

使用示例

<!-- 默认带标题 -->
<ProjectPanelShell title="监控指标">
  <div>内容...</div>
</ProjectPanelShell>

<!-- 标题带图标 -->
<ProjectPanelShell title="监控指标">
  <template #title-icon>
    
  </template>
  <div>内容...</div>
</ProjectPanelShell>

<!-- 隐藏标题 -->
<ProjectPanelShell title="无标题面板" :show-title="false">
  <div>内容...</div>
</ProjectPanelShell>

CardSubTitle

轻量卡片容器组件，无装饰边框，只保留标题栏和内容区。适合嵌套在 ProjectPanelShell 内部做模块分区。

Props

Slots

使用示例

<CardSubTitle title="监控指标">
  <template #header-right>
    <button>更多</button>
  </template>
  <div>内容...</div>
</CardSubTitle>

<!-- 自定义内边距 -->
<CardSubTitle title="监控指标" padding="12px 20px">
  <div>内容...</div>
</CardSubTitle>

GlobalDialog

独立弹窗组件。通常不直接使用，由 DialogContainer 和 dialogService 管理。

Props

DialogContainer

弹窗管理器，内部使用 GlobalDialog 渲染所有打开的弹窗。已在 ProjectScreenRoot 中内置，通常不需要手动引入。

弹窗服务 API

通过 openBigScreenDialog 以编程方式打开弹窗，比声明式组件更灵活。

import { openBigScreenDialog, closeDialog, dialogs } from "yl-big-screen";
import type { DialogItem } from "yl-big-screen";

openBigScreenDialog(options)

打开一个弹窗，返回 Promise（在弹窗关闭时 resolve）。

openBigScreenDialog({
  title: "数据详情",
  component: MyDialogContent,  // Vue 组件
  size: "medium",              // "medium" | "large" | "full"
  props: {                     // 传给 component 的 props
    dataId: "123"
  },
  closeOnClickMask: true,      // 点击遮罩关闭
  onClose: (result) => {       // 关闭回调
    console.log("弹窗关闭，返回:", result);
  },
  onOpen: () => {              // 打开回调
    console.log("弹窗已打开");
  },
  onTitleClick: () => {        // 点击标题回调
    console.log("点击了弹窗标题");
  }
}).then(result => {
  console.log("弹窗已关闭，结果:", result);
});

弹窗内容组件会收到一个 close prop，调用它来关闭弹窗并传回数据：

// MyDialogContent.vue
const props = defineProps({
  dataId: String,
  close: Function
});

function handleConfirm() {
  props.close?.({ status: "ok", data: this.formData });
}

closeDialog(id, result?)

手动关闭指定弹窗。

dialogs

响应式弹窗列表（Ref<DialogItem[]>），用于自定义弹窗逻辑。

背景图

组件内置了默认的页面背景和标题栏背景图（通过 import 打包进 dist，npm 引用时无需额外配置）。

不传 page-background-image / header-background-image 即可使用默认图。

如需自定义，请使用业务项目里能访问到的 URL（public 目录或 import 后的地址），不要使用包内 src/assets 路径：

<script setup>
import myPageBg from "@/assets/my-page-bg.png";
import myHeaderBg from "@/assets/my-header-bg.png";
</script>

<template>
  <ProjectScreenRoot
    :page-background-image="myPageBg"
    :header-background-image="myHeaderBg"
  >
    ...
  </ProjectScreenRoot>
</template>

若传了 page-background-image="/bg/xxx.svg" 但文件不在宿主项目的 public 下，会表现为整页背景不显示，而头部默认图仍正常。

字体

组件标题使用 YouSheBiaoTiHei 字体（有回退：PingFang SC → Microsoft YaHei → sans-serif）。

要在项目中使用该字体，需自行引入字体文件并声明 @font-face：

@font-face {
  font-family: 'YouSheBiaoTiHei';
  src: url('/fonts/YouSheBiaoTiHei.ttf') format('truetype');
}

在线 Demo

在线预览组件效果：GitHub Pages 演示地址

本地开发

# pnpm
pnpm install
pnpm dev

# 或 npm
npm install
npm run dev

启动后打开 http://localhost:3100 查看组件效果。