# 大屏基础模版

**Repository Path**: yaolei123123/large-screen-basic-template

## Basic Information

- **Project Name**: 大屏基础模版
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-21
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 项目git地址
```text
http://192.168.8.86/basic-project/fronted/screen-template
```

## 项目环境
```text
node.js >= 18.18.0
```

## 项目初始化
```text
npm i pnpm -g
pnpm i
```

## 项目启动
```text
pnpm dev
```

## 项目打包
```text
pnpm build
```

## 项目结构

```text
screen-template/
├─ index.html                      # 入口 HTML（Vite 注入构建产物）
├─ package.json                    # 项目依赖与脚本
├─ package-lock.json               # 依赖锁定文件
├─ README.md                       # 项目说明（中文）
├─ tsconfig.json                   # TypeScript 配置
├─ vite.config.ts                  # Vite 构建配置
├─ node_modules/                   # 依赖包目录（自动生成）
├─ public/                         # 公开静态资源（原样拷贝，不经打包处理）
│  ├─ config/                      # 运行时可替换配置
│  │  └─ config.json
│  └─ img/                         # 图片资源（底图、纹理、标记等）
│     ├─ basemaps/                 # 地图底图预览/配置图
│     ├─ marker/                   # 地图标记点素材
│     └─ textures/                 # 地图/3D 材质纹理
└─ src/                            # 源码目录（参与打包）
   ├─ App.vue                      # 根组件（一般承载 router-view、地图）
   ├─ main.ts                      # 应用入口（创建应用/挂载插件）
   ├─ api/                         # 接口请求分模块封装
   │  ├─ common/                   # 公共接口（如文件、媒体）
   │  ├─ home/                     # 首页相关接口
   │  └─ login/                    # 登录相关接口
   ├─ assets/                      # 打包静态资源（会被处理、指纹化）
   │  ├─ icons/                    # 图标资源
   │  │  └─ svg/                   # SVG 图标
   │  ├─ images/                   # 图片（错误页/通用图）
   │  └─ logo/                     # 项目 logo、登录背景等
   ├─ components/                  # 可复用组件
   │  ├─ global/                   # 全局通用组件（如头部）
   │  └─ mars-work/                # 地图场景相关组件与生命周期封装
   ├─ hooks/                       # 组合式 API Hooks（如 ECharts 封装）
   ├─ layout/                      # 页面整体布局（头部/主体等）
   │  ├─ layoutHeader/             # 布局-头部区域
   │  └─ layoutMain/               # 布局-主体区域
   ├─ router/                      # 路由配置与守卫
   ├─ stores/                      # Pinia 状态管理
   ├─ styles/                      # 全局样式与主题
   ├─ types/                       # TypeScript 类型声明与扩展
   ├─ utils/                       # 工具方法与封装（请求、校验、存储等）
   └─ views/                       # 业务页面（路由视图）
      ├─ home/                     # 首页（含地图逻辑）
      └─ login/                    # 登录页
```

# 前端规范

## 1、项目命名
```javascript
// 【建议】
mall-management-system
// 【反例】
mall_management-system/ mallManagementSystem
```
##2、目录命名
全部采用小写方式， 以中划线分隔，有复数结构时，要采用复数命名法， 缩写不用复数。
```javascript
// 【建议】
scripts / styles / components / images / utils / layouts / demo-styles / demo-scripts / img / doc
// 【反例】
script/ style / demo_scripts / demoStyles / imgs / docs
```
## 3、JS 、CSS 、SCSS 、HTML 、PNG  文件命名
全部采用小写方式， 以中划线分隔。
```javascript
// 【建议】
render-dom.js / signup.css / index.html / company-logo.png
// 【反例】
renderDom.js / UserManagement.html
```
## 4、命名严谨性
代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。 说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免
```javascript
// 【建议】
henan / luoyang/ rmb  等国际通用的名称，可视同英文
// 【反例】
DaZhePromotion [打折] / getPingfenByName() [评分] /int  某变量 =3
// 杜绝完全不规范的缩写，避免望文不知义：
// 【反例】
AbstractClass “缩写”命名成 AbsClass；condition “缩写”命名成 condi ，此类随意缩写严重降低了代码的可阅读性。
```
杜绝完全不规范的缩写，避免望文不知义：

## 5、css命名
1、类名使用小写字母，以中划线分隔
2、采用驼峰式命名
3、sass中的变量、函数、混合、placeholder  采用驼峰式命名

## 6、Javascript命名
1、采用小写驼峰命名 lowerCamelCase，代码中的命名均不能以下划线，也不能以下划线或美元符号结束
```javascript
// 【建议】
myName
// 【反例】
_name / name_ / name$
```
2、方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase  风格，必须遵从驼峰形式
```javascript
// 【建议】
localValue /getHttpMessage()/ inputUserId

*其中 method  方法命名必须是 动词 或者 动词+名词 形式*
// 【建议】
saveShopCarData /openShopCarInfoDialog
// 【反例】
save / open / show / go
```
3、常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长
```javascript
// 【建议】
MAX_STOCK_COUNT
// 【反例】
MAX_COUNT
```
## 7、使用 ES6+
必须优先使用 ES6+   中新增的语法糖和函数。这将简化你的程序，并让你的代码更加灵活和可复用。比如箭头函数、await/async  ， 解构， let   ， for …of  等等。
## 8、函数定义
业务开发中提倡的做法, 箭头函数配合const函数一起使用
```javascript
// 【建议】
const getTableListData = () => { // TODO }
// 【反例】尽量不要出现混用，如下：
function getDomeData () {}
const getDome1Data = () => {}
```

## 9、变量定义
在项目或者开发过程中，尽量使用let或者const定义变量，可以有效的规避变量提升的问题，不在赘述，注意const一般用于声明常量或者值不允许改变的变量。

```javascript
// 【建议】
const myName = "张三"
let myName = "张三"
// 【反例】
var myName = "张三"
```
## 10、条件判断和循环最多三层
条件判断能使用三目运算符和逻辑运算符解决的，就不要使用条件判断，但是谨记不要写太长的三目运算符。如果超过 3  层请抽成函数，并写清楚注释。
## 11、请求数据
数据请求类、异步操作类需要使用try…catch捕捉异常。尽量避免回调地狱出现。

```javascript
// 【建议】
/**
 * @description 获取列表数据
 * @return void
 */
const getTableListData = async () => {
  // 自己的业务处理TODO
  try {
    const res = await getTableListDataApi();
    // TODO
  } catch (error) {
    // 异常处理相关
  } finally {
    // 最终处理
  }
};

//【提倡】推荐接口定义带着Api结尾，比如我的方法是getTableListData，
//【提倡】内部逻辑调用的后端接口，那我的接口便可以定位为getTableListDataApi。
```
# 2、Vue 项目规范
## 1、组件文件名为 pascal-case  格式
组件名应该始终是多个单词组成（大于等于 2），且命名规范为 kebab-case 格式。这样做可以避免跟现有的以及未来的 HTML  元素相冲突，因为所有的 HTML   元素名称都是单个单词的。
```javascript
// 【建议】
components/
|- my-component.vue
// 【反例】
components/
|- myComponent.vue
|- MyComponent.vue
```
## 2、基础组件文件名为 base  开头，使用完整单词而不是缩写
```javascript
// 【建议】
components/
|- base-button.vue
|- base-table.vue 
|- base-icon.vue
// 【反例】
components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue
```
## 3、和父组件紧密耦合的子组件应该以父组件名作为前缀命名
```javascript
// 【建议】
components/ 
|- todo-list.vue
|- todo-list-item.vue
|- todo-list-item-button.vue
|- user-profile-options.vue  （完整单词）
// 【反例】
components/ 
|- TodoList.vue
|- TodoItem.vue  
|- TodoButton.vue
|- UProfOpts.vue  （使用了缩写）
```
## 4、文件命名
功能菜单的入口文件一定要带着name，同时其他编写的业务组件也推荐带着name，同时name的命名规则大写驼峰，且尽量要全局唯一(避免后期定位问题增加复杂度)。

```javascript
<script setup  name='CustomName'> </script>
```
## 5、响应性变量
合理的使用响应性变量。数据量很大的对象或者数组，同时属性又是嵌套的对象，你的业务场景只需要第一层属性具有响应性，推荐使用shallowRef和shallowReactive定义响应性变量，这时不在推荐使用ref和reactive了。
## 6、必须为 v-for 设置键值 key

## 7、v-show  与 v-if  选择
如果运行时，需要非常频繁地切换，使用 v-show  ；如果在运行时，条件很少改变，使用 v-if。

## 8、Hooks使用
在Vue3的项目中强烈推荐使用hooks进行功能的拆分和复用，下面来看一个列子，比如说，我要实现一个弹框的功能，下面常见的写法：

```javascript
const useEditModel = () => {
  const isShow = ref(false);

  /**
   * 显示弹框
   */
  const showModal = () => {};

  /**
   * 关闭弹框
   */
  const cancelModal = () => {};

  /**
   * 提交操作
   */
  const submitModal = () => {};

  onBeforeMount(() => {
    // TODO
  });

  return {
    isShow,
    showModal,
    cancelModal,
    submitModal,
  };
};

// 其他地方使用
const { isShow, showModal, cancelModal, submitModal } = useEditModel();
```

## 9、代码注释 （vscode插件koroFileHeader ctrl+win+t 不起作用说明快捷键冲突）
功能开发时编写的相关方法要进行方法注释和说明，注释要遵循JSDOC规范。

```javascript
/**
 * @description: 方法描述 （可以不带@description）
 * @param {参数类型} 参数名称
 * @param {参数类型} 参数名称
 * @return 没有返回信息写 void / 有返回信息 {返回类型} 描述信息
 */
 // 示例
 /**
 * @description 获取解析统计相关数据
 * @param {Object} userInfo
 * @param {Array} lists
 * @param str 当前值字符串
 * @return void
 */
```

## 10、动态图片url
为避免vite打包跳过动态图片url导致生产环境图片不显示，需按规范进行动态url引入
```javascript
//可正常使用
const images = import.meta.glob('../../assets/images/home/zy-*.png', { eager: true })
const url = images[`../../assets/images/home/zy-${type}.png`] as any
let obj = {
    name: item.table_name,
    num: item.count,
    unit: item.table_name == '应急专家' ? '人' : '个',
    url: url && url.default,
}
list.value.push(obj)
//不能正常使用 对于不确定的静态资源会跳过引入
let obj = {
    name: item.table_name,
    num: item.count,
    unit: item.table_name == '应急专家' ? '人' : '个',
    url: new URL('../../assets/images/home/zy-' + type + '.png', import.meta.url).href,
}
list.value.push(obj)
```

## 11、props使用
避免解构props,会导致数据失去响应式
```javascript
//会失去响应式
const { eventDetail, eventTaskTj } = defineProps<{
    eventDetail?: EventVO;
    eventTaskTj?: EventTaskTjVO
}>();
//不会丢失响应式
const props=defineProps<{
    eventDetail?: EventVO;
    eventTaskTj?: EventTaskTjVO
}>()
const { eventDetail, eventTaskTj } =toRefs(props);
```
# 3、新增文件规范
### 1、新增view
在 @/views文件夹下 创建对应的文件夹，一般性一个路由对应一个文件， 该模块下的功能就建议在本文件夹下创建一个新文件夹，各个功能模块维护自己的utils或components组件。

### 2、新增api
在 @/api文件夹下 创建对应的文件夹，一般与@/views文件夹对应，各个功能模块维护自己的index.ts或type.ts。

```javascript
// index.ts 文件内容如下
import request from '@/utils/request';
import { StatisticsDataVo } from './types';

/**
 * @description: 查询统计数据
 * @param {object} params 
 * @return {*} {Promise<any>}
 */
export function getStatisticsData(params: StatisticsDataVo) {
    return request({
        url: '/home/statistics',
        method: 'GET',
        params
    });
}
// type.ts 文件内容如下
export interface StatisticsDataVo {
    total: number;
    active: number;
    inactive: number;
}
```


### 3、新增组件
在全局的 @/components 文件夹写一些全局的组件，如富文本，各种搜索组件，封装的分页组件等等能被公用的组件。 每个页面或者模块特定的业务组件则会写在当前 @/views下面。 如：@/views/system/components/xxx.vue。这样拆分大大减轻了维护成本

### 4、地图相关
1、项目中全局引用了mars3d 各个用到地图的组件在自己的文件夹下面建一个map.ts文，该文件维护该组件地图相关的操作。
2、全局的地图方法可以写在@/utils/map.ts文件中


```javascript
// 组件中使用
// 导入生命周期钩子
import useLifecycle from "@/components/mars-work/use-lifecycle";
// 导入地图相关功能
import * as mapWork from "./map";
useLifecycle(mapWork);


// map.ts 文件内容如下
import * as mars3d from "mars3d";
let map: mars3d.Map; // 地图对象

// 初始化当前业务
export async function onMounted(mapInstance: mars3d.Map): Promise<void> {
  map = mapInstance; // 记录map
}

// 释放当前业务
export function onUnmounted(): void {
  if (!map) {
    return;
  }
  map = null;
}
```