展厅项目技术文档

项目概述

这是一个基于 Vue 3 + TypeScript + Vite 的大屏可视化项目，采用 1920x1080 设计稿尺寸，使用 SCSS Mixin 实现自适应布局。

一、核心设计参数

$designHeight: 1080;   // 设计稿高度
$designWidth: 1920;    // 设计稿宽度

所有自适应 mixin 都基于这两个参数进行换算。

二、SCSS Mixin 详解

2.1 尺寸自适应函数

`vw($px)` - 宽度自适应

将设计稿的像素值转换为响应式的 vw 单位。

// 设计稿中 100px 的元素
width: vw(100);  // => calc((100 * 100 * 1vw) / 1920)
// 在不同屏幕下自动缩放

公式: (设计稿px值 * 100vw) / 设计稿宽度

`vh($px)` - 高度自适应

height: vh(50);  // => calc((50 * 100 * 1vh) / 1080)

公式: (设计稿px值 * 100vh) / 设计稿高度

`vwh($w, $h)` - 同时设置宽高

@include vwh(1920, 1080);  // 宽度和高度同时自适应
// 等价于
width: vw(1920);
height: vh(1080);

`width($px)` / `height($px)`

这两个函数内部调用了 vw() 和 vh()，用法相同：

width: width(200);  // 等同于 vw(200)
height: height(100);  // 等同于 vh(100)

2.2 布局 Mixin

`@include flex` - Flex 布局（水平排列）

.container {
  @include flex;
  // 展开后:
  // display: flex;
  // justify-content: flex-start;  // 左对齐
  // align-items: center;          // 垂直居中
}

`@include flexc` - Flex 居中

.box {
  @include flexc;
  // 展开后:
  // display: flex;
  // justify-content: center;  // 水平居中
  // align-items: center;      // 垂直居中
}

`@include flexd` - Flex 纵向排列（常用于上下结构）

.card {
  @include flexd;
  // 展开后:
  // display: flex;
  // justify-content: center;
  // align-items: flex-start;
  // flex-direction: column;  // 垂直方向
}

2.3 文本溢出 Mixin

`@include ellipsis` - 单行省略

.title {
  @include ellipsis;
  // white-space: nowrap;
  // overflow: hidden;
  // text-overflow: ellipsis;
}

`@include ellip` - 同上的单行省略（重复定义，择一使用）

`@include ellipsis2` / `@include ellipS` - 多行省略（2行）

.desc {
  @include ellipsis2;
  // display: -webkit-box;
  // -webkit-line-clamp: 2;
  // -webkit-box-orient: vertical;
  // overflow: hidden;
}

2.4 背景与定位

`@include bgImg($url)` - 背景图片拉伸

.banner {
  @include bgImg('@/assets/banner.png');
  // background: url(...) no-repeat;
  // background-size: 100% 100%;
}

`@include pa` - 绝对定位（左上角）

.overlay {
  @include pa;
  // position: absolute;
  // left: 0;
  // top: 0;
}

2.5 滚动条样式

`@include scrool` - 竖向滚动条自定义

.content {
  @include scrool;
  // 自定义滚动条样式
  // &::-webkit-scrollbar { width: vw(5); }
  // &::-webkit-scrollbar-thumb { ... }
  // &::-webkit-scrollbar-track { ... }
}

`@include scroolX` - 横向滚动条

宽度设为 height(5)，用于横向滚动场景。

`@include hideScrool` - 隐藏滚动条（但可滚动）

滚动条极细（width(3)），视觉上隐藏但功能可用。

2.6 清除浮动

`@include clearFloat`

用于 BFC 或 clearfix：

.parent::after {
  @include clearFloat;
  // content: "";
  // display: block;
  // height: 0;
  // clear: both;
}

2.7 文本渐变

`@include fontColorGradient($color1, $color2, $color3)`

三色渐变文字（常用于标题）：

.gradient-text {
  @include fontColorGradient(#88BAFF, #E3FEFF, #ffffff);
  // background: linear-gradient(0deg, #88BAFF 0%, #E3FEFF 50%, #ffffff 100%);
  // -webkit-background-clip: text;
  // -webkit-text-fill-color: transparent;
}

参数默认值：

$m: #88BAFF - 渐变起始色
$k: #E3FEFF - 渐变中间色
$n: #ffffff - 渐变结束色

2.8 动画

`@include ani($animationName, $duration: 1.5s, $fillMode: none)`

快速应用动画：

.box {
  @include ani(slideUpDown, 2s, forwards);
}

支持两种写法：

完整动画名：slideUpDown
以 animate__ 开头的类名（如 animate__fadeIn），会自动截取 fadeIn

项目中已定义的动画 keyframes：

trailingAni - 拖尾流星
picturepoint - 图片焦点上升
slideUpDown - 上下跳动
floatUpDown - 上下漂浮
breathing - 呼吸效果

2.9 工具函数

`stripUnit($number)` - 去除单位

width: vw(100px);  // 内部会调用 stripUnit(100px) => 100

`middleStr($str)` - 截取字符串后半部分

$result: middleStr('Hello');  // => 'lo'

三、常用场景示例

1. 全屏容器（保持 16:9 比例）

<template>
  <div class="screen-container">
    <!-- 内容 -->
  </div>
</template>

<style scoped>
.screen-container {
  @include vwh(1920, 1080);  // 设计稿尺寸
  margin: 0 auto;
}
</style>

2. 居中弹窗

.modal {
  @include flexc;           // flex 居中
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  z-index: 1000;
}

3. 标题行超出省略

.title {
  @include ellipsis;        // 单行省略
  font-size: vw(18);
  color: #fff;
}

4. 两行描述文本

.description {
  @include ellipsis2;       // 两行省略
  font-size: vw(14);
  line-height: vh(24);
}

5. 自定义滚动列表

.list {
  height: vh(500);
  overflow-y: auto;
  @include scrool;          // 美化滚动条
}

6. 图标背景

.icon {
  @include bgImg('@/assets/icons/arrow.png');
  @include vwh(40, 40);     // 宽度和高度自适应
}

四、使用建议

✅ 推荐做法

所有尺寸使用 vw/vh

// 好
width: vw(200);
margin: vh(10) vw(20);

// 避免
width: 200px;  // 不会自适应

布局优先用 flex mixin

.row {
  @include flex;      // 水平排列
}
.center {
  @include flexc;     // 居中
}

文本超出统一用 ellipsis 系列
滚动区域加 @include scrool 美化

⚠️ 注意事项

vw/vh 基于设计稿 1920x1080，如果设计稿不同，需修改 $designWidth 和 $designHeight

字体不要用 vw/vh：字体过小会看不清，通常固定 px 或 rem。建议：

// 基准字体（不随屏幕缩放）
font-size: 14px;

// 标题可以用 vw 适度放大
h1 { font-size: vw(24); }

边框、阴影慎用 vw/vh：太小的边框（如 1px）转换后可能模糊，建议固定：
```
border: 1px solid #fff;  // 保持 1px
```
图片自适应：@include bgImg 会拉伸背景，如果不想拉伸，用 object-fit:
```
img {
  width: vw(100);
  height: vh(100);
  object-fit: cover;
}
```

五、项目结构

src/
├── mixin.scss          # 所有 mixin 定义（全局引入）
├── style.css           # 全局样式重置
├── main.ts             # 入口文件（引入了 style.css 和 mixin.scss）
├── App.vue             # 根组件
├── components/         # 公共组件
├── views/              # 页面组件
├── assets/             # 静态资源
│   └── iconfont.scss   # 图标字体
├── utils/              # 工具函数
├── api/                # 接口
├── router/             # 路由
├── store/              # Pinia store
└── interfaces/         # TypeScript 类型

全局引入方式（通常在 main.ts 中）：

import { createApp } from 'vue'
import App from './App.vue'
import './style.css'
import './mixin.scss'  // mixin 全局可用
import router from './router'
import { createPinia } from 'pinia'

createApp(App).use(router).use(createPinia()).mount('#app')