前端编码规范

变量及注释

• 1.变量命名需要采用语义化命名，不要出现a,b,c,d等。
• 2.变量名及部分函数需要增加注释，近可能简短重点表达其含义
• 3.函数逻辑变更时，及时更新注释。
• 4.常量及不会再次赋值的变量使用const

枚举

需要将枚举类型抽象到单独文件中，例如：、

export const PRODUCTION_TYPE = {
    0: '线下',  1: '线上'}
...
import { PRODUCTION_TYPE } from './enum.ts'
type ProductionType = typeof PRODUCTION_TYPE

Request

需要以组件为单位去新建请求api

widgets/[组件]/api/index.ts
import sdk from 'sdk'
const { request } = sdk.utils
// 获变量绑定
function getVariableBinding() {
  const url = `/api/v1/showroom/dashboard/binding`
  const method = 'get'
  return sdk.request({ url, method })
}

组件引入

检查组件依赖关系，尽可能避免循环依赖

Typescript

命名约定

• 1.使用驼峰式命名：变量、函数和方法名首字母小写，类名首字母大写。
• 2.使用描述性名称，避免使用缩写除非是通用缩写（如 HTTP）。

类型定义

• 1.明确指定变量、函数参数和返回值的类型。
• 2.尽可能使用 TypeScript 内置的基本类型（如 number, string, boolean 等）或自定义类型。 使用接口和类型别名 利用接口和类型别名来定义自定义数据类型和结构。 避免使用 any 类型 尽量避免使用 any 类型，除非必要，因为它会破坏 TypeScript 的类型检查。

文件命名

采用首字母大写，中间不加横岗

.vue文件：Test.vue
.tsx文件：Test/Test.tsx

空格缩进

设置文件新建时，缩进为2个字符

css规范

模版开发时，需要使用scoped进行作用域设置

<style lang='scss' scoped>
...
</style>

class命名

采用连接符号'-'进行分割，保证语义化

如：.list-box .content等

禁止使用全局class修改样式，譬如公共组件等，如果是vue文件，一律写在scope下

<style lang="scss" scoped>
...
</style>

tsx方式开发时

采用模块化的方式，例如：

禁止使用全局class修改样式，譬如公共组件等，如果是scss文件，一律通过styles进行引入

import styles from './Variable.module.scss'
// ...
<div class={styles.box}>...</div>

配置

开发一个组件，需要在src/widgets 下新建文件夹，文件夹命名需要保证跟src/widgets/index.ts中的name一致，如下：

import Example from './Example.vue'
import ExampleSettings from './Example.settings.vue'
import { provider } from '@/provider/index'

export default {
  is: 'Example',
  name: '例子',
  category: 'run',
  authorizationRequired: true,
  icon: 'icon-tiaomaguanli',
  canvasView: provider(Example),
  settingsView: ExampleSettings,
}

需要注意的是，authorizationRequired: true 在cms2.2.0后，需要进行组件授权才可使用。 关于provider，是针对cms2.0中二开组件样式会被影响所采取的方案，使用element-plus中的作用域进行封装，可以解决在开发中存在的样式冲突与zIndex等全局问题。

import { h } from 'vue'
import Provider from './index.vue'

export const provider = (Widget: any) => {
  return (arg: any) => {
    return h(Provider, null, {
      default: (props: any) => {
        return h(Widget, {
          props,
          ...arg,
        })
      },
    })
  }
}

变量弹窗

可以使用组件提供已经封装好的Variable组件进行开发

import Variable from '@/components/Variable/Variable'

具体参考组件文档

代码行数

单个文件内容函数，不能超过500行，有单独功能需要抽离进行封装引用，保证代码可读性 console 提交git记录时，需清除页面中所有的console和的debugger 判断 当设计判断时，能使用绝对等号(===)就不要使用==，去除隐式转换，保证代码健壮性 如：

const a = 1
const b = '1'
if(a === b) {
    // ...
}

DOM与选择器

尽量避免在代码中使用document等Dom操作符，可以使用ref来获取dom

<div ref="divRef"><div>

分号

代码结束后，无需写”;“，换行即可 需保证代码格式化的正常

注释

每个变量及函数，需要进行注释，保证后续维护的可读性

变量声明

禁止使用var，需使用let与const 对于可变变量使用let，常量使用const

hook及命名

禁止使用前缀 _, $_等特殊前缀命名，命名要语义化

// ok:
let max = 100
let min = 0
// err: 
let _max = 100
let _min = 10

语义化命名，禁止使用中文和拼音和数字

// ok
let success = true
// err
let 成功 = true
let chengong = true

组件hook暴露要变量和方法放一起，不要混乱

事件命名

事件命名需要以on开头 比如：

return {
    onBeforeUpload,
    onError,
    onSuccess,
    openDetail,
    onBeforeLoad,
    onSearch,
    onExport,
    onRowClick,
    onConfirmWorkSection,
    onCheck,
    onAddProcess,
    onGroupChange,
  }

条件

禁止使用中文名甚至多语言返回值作为对比

// ok
if (a === 1) {
  return true
}
// err
if (a === "你好") {
  return true
}
if (a === _t("你好")) {
  return true
}

🧹 Vue3 + TS 项目代码规范问题清单（InspectionRecords.vue）

命名与结构

问题 建议 示例 组件名首字母大写写

err:
<pascalCase /> <inspectionRecords /> 
ok:
<PascalCase/>	<InspectionRecords/> 

需驼峰命名，语义化

err:
getproductListFn 命名不规范	
ok:
驼峰命名统一风格，改为 getProductList	
// 语义化
err:
exportJudgmentFn 冗余后缀	
ok:
去掉 Fn，改为 exportJudgment	

watch 使用问题

err:
watch(curTab) 逻辑复杂，不易维护	
ok:
抽成 useTabEffect() 组合函数
err:
多个 watch 监听日期，重复提醒	
ok:
合并处理逻辑，统一提示控制逻辑

使用组合式 API 更清晰的封装：

ok:
useFilterForm()
useTablePagination()
useExportAction()
ok:
  加入 TS 类型定义（如接口、响应结构体）
ok:
  将请求模块与逻辑代码分离，保持组件纯净性

Git规范

✅ Git 使用规范（提交信息 & 分支命名）

一、提交信息规范（Commit Message）

使用 Conventional Commits 格式，确保提交记录清晰、可读、可追溯。

格式规范：

[bugId] 简要描述

提交类型说明：

类型	说明	示例
feat	新功能、新模块	feat: 添加用户登录功能
fix	修复 bug，需附 bugId 和问题描述	fix:#123 修复表格显示异常
docs	仅修改文档或注释，不影响功能	docs: 更新项目使用说明文档
style	代码格式调整（不影响逻辑、功能）	style: 调整缩进与代码对齐方式
refactor	重构代码（非功能性优化）	refactor: 抽离公共方法简化逻辑
perf	性能优化相关改动	perf: 减少数据库查询次数
test	增加测试代码、单元测试、集成测试等	test: 增加表单校验的单元测试
chore	杂项变更，如构建脚本、工具升级等	chore: 升级 eslint 版本
revert	回退某次提交	revert: 回退功能X的提交
build	打包构建相关改动	build: 打包配置调整

二、分支命名规范

统一使用小写英文、/ 分隔，多人协作时建议带上用户标识。

命名格式：

类型/用户/模块名

常用分支类型：

分支类型	用途描述	命名示例
feature	开发新功能	feature/zhangsan/login-page
fix	修复 bug	fix/lisi/user-list
release	发布准备分支	release/0612
hotfix	线上紧急修复（可选）	hotfix/zhangsan/payment-bug
test	临时测试分支（如集成测试）	test/dev-feature-x

三、推荐工作流（基于 Git Flow）

main ← 线上部署主分支 │ ├─ release/0612 ← 发布版本分支（测试阶段） │ ├─ feature/xx/module ← 开发功能分支 │ ├─ fix/xx/module ← 修复问题分支 │ └─ hotfix/xx/xxx ← 紧急修复分支（可选）