版本：Next

前端编码规范

变量及注释

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 ← 紧急修复分支（可选）

变量及注释​

枚举​

Request​

组件引入​

Typescript​

命名约定​

类型定义​

文件命名​

空格缩进

css规范

class命名​

tsx方式开发时​

配置​

变量弹窗​

代码行数​

DOM与选择器​

分号​

注释​

变量声明​

hook及命名​

事件命名​

条件​

命名与结构​

需驼峰命名，语义化​

watch 使用问题​

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

Git规范​

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

格式规范：​

提交类型说明：​

二、分支命名规范​

命名格式：​

常用分支类型：​

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