开发者文档

Appearance

本页导航

目录&文件命名 ​

【强制】

使用统一小写的英文字母（统一翻译的英文名字）， 数字和中划线的组合， 不得包含汉字，空格和特殊字符

  • index.ts
  • product-list/index.ts
  • msg-card/index.ts
  • Constants/EnvConstants.ts 【这里所有常量都是大驼峰命名方式】
  • utils/Common.ts 【类也是大驼峰命名方式】

错误示例

  • product_list
  • productList
  • record@x3.png 【特别注意不得包含特殊字符】

变量命名 ​

【强制】

使用统一小写的英文字母（统一翻译的英文名字）， 数字和中划线的组合， 不得包含汉字，空格和特殊字符 ，这里常用let 和 const声明变量

ts
const CONSTANT_TEST = 'CONSTANT_TEST'  // 这里是个常量，通常用于映射字段或一个标识，可以用下划线
const str = 'string'
const num = 1
const boolean = true
const list = []
const userInfo = {}
function doSomething() {}
async getSomething() {}
const walk = () => {}
const think = async () => {}
class Person {}              // 所有的类都以大驼峰写法命名
const CONSTANT_TEST = 'CONSTANT_TEST'  // 这里是个常量，通常用于映射字段或一个标识，可以用下划线
const str = 'string'
const num = 1
const boolean = true
const list = []
const userInfo = {}
function doSomething() {}
async getSomething() {}
const walk = () => {}
const think = async () => {}
class Person {}              // 所有的类都以大驼峰写法命名

Less样式命名 ​

【强制】

使用统一的预处理语言Less，每层嵌套不得超过三层，class命名也是小写英文字母，数字和中划线的组合，不得包含汉字，空格和特殊字符

less
// 特别注意，不得超过3层
.home {
  .head {}
  .body {}
  .foot {}
  .msg-card {}
}
// 特别注意，不得超过3层
.home {
  .head {}
  .body {}
  .foot {}
  .msg-card {}
}

注释规范 ​

【强制】

什么时候用//，什么使用用/** */ 取决于是否方法或者属性需要提示，方法都使用多行注释才能提示

ts
// 页面状态
const state = reactive({
  ...
})
/** 做些什么 */
function doSomething() {}

/**
 * 获取研报数据
 * @param id {string} 研报id
 */
function getReportList(id: string) {} 

interface UserParams {
  /** 用户名 */
  username: string;
  /** 年龄 */
  age: number;
  /** 体重 */
  weight: number;
  /** 身高 */
  tall: number;
}
/**
 * 保持用户配置
 * @param params.username 用户名
 * @param params.age 年龄
 * @param params.weight 体重
 * @param params.tall 身高
 */
function saveUser(params: UserParams) {}
// 页面状态
const state = reactive({
  ...
})
/** 做些什么 */
function doSomething() {}

/**
 * 获取研报数据
 * @param id {string} 研报id
 */
function getReportList(id: string) {} 

interface UserParams {
  /** 用户名 */
  username: string;
  /** 年龄 */
  age: number;
  /** 体重 */
  weight: number;
  /** 身高 */
  tall: number;
}
/**
 * 保持用户配置
 * @param params.username 用户名
 * @param params.age 年龄
 * @param params.weight 体重
 * @param params.tall 身高
 */
function saveUser(params: UserParams) {}

Typescript 类型 ​

【强制】

采用大驼峰方式声明类型，type一般用来声明基本数据类型，interface一般用来声明引用数据类型，如果涉及请求接口类型通过 @cixjs/cli 脚手架生成接口类型文件

typescript
type Key = 'Apple' | 'Blue' | 'Car'
interface Params {
  /** 页数 */
  pageSize: number;;
  /** 当前页 */
  page: number;
}
interface Result {
  total: numebr;
  pages: number;
  ...
}
async function getSomething(id: string): Promise<Result> {}
async function getSomething(params: Parmas): Promise<Result> {}

// 选择pageSize类型
type PageSize = Pick<Params, 'pageSize'>

// 过滤total类型
type ExcludeTotal = Omit<Params, 'total'>

// 复制类型
type Key2 = typeof Key

// 继承类型
interface Params2 extends Param {
  sort: string;
}
type Key = 'Apple' | 'Blue' | 'Car'
interface Params {
  /** 页数 */
  pageSize: number;;
  /** 当前页 */
  page: number;
}
interface Result {
  total: numebr;
  pages: number;
  ...
}
async function getSomething(id: string): Promise<Result> {}
async function getSomething(params: Parmas): Promise<Result> {}

// 选择pageSize类型
type PageSize = Pick<Params, 'pageSize'>

// 过滤total类型
type ExcludeTotal = Omit<Params, 'total'>

// 复制类型
type Key2 = typeof Key

// 继承类型
interface Params2 extends Param {
  sort: string;
}

主题配置 ​

【强制】框架中所有的颜色值都会跟随主题而变动。开发时，颜色值需要使用 变量代替(运营类的业务除外)。

系统内置主题模式:

  • light 浅色模式
  • dark 深色模式

系统内置主题色位于 src/cix/style/standardTheme.less<br /> 如需定制化，可新建 src/static/css/theme.less

主题切换 ​

  • URL链接中附加参数 theme=light/dark 可切换
  • 调用API Theme.setTheme(theme) 可切换

使用 ​

业务代码中直接使用变量值替代对应的颜色值

vue
// less
.content{
    color: var(--cr-font-main);
}

// html
<div :class="{style: var(--cr-font-main)}"></div>
// less
.content{
    color: var(--cr-font-main);
}

// html
<div :class="{style: var(--cr-font-main)}"></div>

| 可以参考【研报精选】项目实现

字体规范 ​

【强制】一般情况下，开发者无需关注默认字体配置，也 禁止在css中配置 font-family 来指定字体。

系统内置字体如下:

  • SF Display 苹方 默认英数字体
  • DIN DIN字体
  • DIN Pro DIN字体(Bold)
  • HarmonySans 鸿蒙 默认特殊英数字体
  • HarmonySans-Bold 鸿蒙(Bold)

开发者需要关注特殊字体的使用，系统已内置常用特殊字体的类名，在需要的DOM标签中引入 class类名使用即可。

系统内置特殊字体class类名如下:

  • font-bold 文字加粗
  • font-number 特殊数字
  • font-number-bold 特殊数字加粗

使用示例:

html
<div class="font-bold">加粗文本</div>
<div class="font-number">特殊数字</div>
<div class="font-number-bold">加粗特殊数字</div>
<div class="font-bold">加粗文本</div>
<div class="font-number">特殊数字</div>
<div class="font-number-bold">加粗特殊数字</div>
  • 特殊字体使用范围(醒目数字、涨跌幅、价格、重要数字、重要英文文字等)，

全局数据获取 ​

按照Cix框架模板构建的业务项目，框架会对 每个业务页面或自定义组件的data进行通用数据赋值,业务开发者可以直接在DOM或业务逻辑中直接使用。

生命周期 created 执行数据赋值。需注意,组件如需生效，需在 data中配置属性 cixComponent: true 来启用

  • 通用赋值数据如下(可通过 this查看):
typescript
data.cd = {
  // 当前主题
	autoTheme: "light/dark",
  // CDN基础路径
  cdnBase: "https://storage.txyun.investoday.net/storage",
  // CDN 图片路径根目录
  cdnImg: "https://storage.txyun.investoday.net/storage/cdn/images",
  // 是否深色模式
  isDark: false,
  // 当前链接参数
  query: {},
  cr: {
    // 右箭头颜色
    arrowRight: "#BABABA",
    // 灰色文字颜色
    fontGrey: "#666666",
    // 浅灰色文字颜色
    fontLightGrey: "#666666",
    // 一级文字颜色
    fontMain: "#ffffff",
    // 主要特殊文字颜色
    fontMainSpec: "#AF7441",
    // 二级文字颜色
    fontSecond: "#999999",
    // 次级特殊文字颜色
    fontSecondSpec: "#DCB77E",
    // 高亮色
    highLight: "#5F77FF",
    // 主题色
    main: "#5F6BFF",
    // 主体相似色
    similar: "#FFFFFF"
  },
  lay: {
    // 菜单按钮左边距
    menuButtonLeft: 0,
    // 菜单按钮宽度
    menuButtonWidth: 0,
    // 导航栏高度
    navHeight: 44,
    // 状态栏+导航栏高度
    navHeightX: 64,
    // 屏幕高度
    screenHeight: 667,
    // 屏幕宽度
    screenWidth: 375,
    // 状态栏高度
    statusHeight: 20,
    // 窗口高度
    windowHeight: 667,
    // 窗口宽度
    windowWidth: 375,
     // 安全区域
    safeArea: {
      // 安全区域左上角横坐标
      left: 0,
      // 安全区域右下角横坐标
      right: 0,
      // 安全区域顶部纵坐标
      top: 0,
      // 安全区域底部纵坐标
      bottom: 0,
      // 安全区域的宽度
      width: 0,
      // 安全区域的高度
      height: 0,
      // 底部距离
      bottomX: 0
    }
  }
}
data.cd = {
  // 当前主题
	autoTheme: "light/dark",
  // CDN基础路径
  cdnBase: "https://storage.txyun.investoday.net/storage",
  // CDN 图片路径根目录
  cdnImg: "https://storage.txyun.investoday.net/storage/cdn/images",
  // 是否深色模式
  isDark: false,
  // 当前链接参数
  query: {},
  cr: {
    // 右箭头颜色
    arrowRight: "#BABABA",
    // 灰色文字颜色
    fontGrey: "#666666",
    // 浅灰色文字颜色
    fontLightGrey: "#666666",
    // 一级文字颜色
    fontMain: "#ffffff",
    // 主要特殊文字颜色
    fontMainSpec: "#AF7441",
    // 二级文字颜色
    fontSecond: "#999999",
    // 次级特殊文字颜色
    fontSecondSpec: "#DCB77E",
    // 高亮色
    highLight: "#5F77FF",
    // 主题色
    main: "#5F6BFF",
    // 主体相似色
    similar: "#FFFFFF"
  },
  lay: {
    // 菜单按钮左边距
    menuButtonLeft: 0,
    // 菜单按钮宽度
    menuButtonWidth: 0,
    // 导航栏高度
    navHeight: 44,
    // 状态栏+导航栏高度
    navHeightX: 64,
    // 屏幕高度
    screenHeight: 667,
    // 屏幕宽度
    screenWidth: 375,
    // 状态栏高度
    statusHeight: 20,
    // 窗口高度
    windowHeight: 667,
    // 窗口宽度
    windowWidth: 375,
     // 安全区域
    safeArea: {
      // 安全区域左上角横坐标
      left: 0,
      // 安全区域右下角横坐标
      right: 0,
      // 安全区域顶部纵坐标
      top: 0,
      // 安全区域底部纵坐标
      bottom: 0,
      // 安全区域的宽度
      width: 0,
      // 安全区域的高度
      height: 0,
      // 底部距离
      bottomX: 0
    }
  }
}

分支&版本号命名 ​

【强制】统一开发模式：dev；主分支：main；打tag统一用main分支

一般命名用功能特性，问题模块，页面小写英文命名。打tag一般以版本号加日期打tag

功能开发、优化以及bug修复分支命名如下，所有分支都从dev分支检出 ​

  • feat/xxx【新功能】
  • perf/xxx【优化】
  • fix/xxx【修复】

生产tag命名如下，所有tag都从main分支打tag ​

  • v1.0.1_20230710【bug，样式，小调整在第3位递增1】
  • v1.1.0_20230710【模块，页面，新功能在第2位递增1】
  • v2.0.0_20230710【大改动，框架，或者具有里程碑的改动在第1位置递增1】

开发时注意 ​

遇到判断时，如果能用map则用map，超过以及3个if，用switch代替

ts
// 这里用object来映射关系，扩展性好，不受key改变调整数据结构
const TypeObjMap = {
  0: '未参与',
  1: '已参与',
  2: '已猜中'
}

// 这里用array来映射关系，受索引来映射关系，如果key改为字符串则需要转换数据格式
const TypeArrMap = ['未参与', '已参与', '已猜中']

const typeText = TypeObjMap[type]
const typeText2 = TypeArrMap[type]


// 错误示范
if (type === 0) { 
  return '未参与' 
} else if (type === 1) { 
  return '已参与 
} else if (type === 2) { 
  return '已猜中' 
} 
// 最佳示范
switch (type) { 
  case 0: 
    return '未参与' 
  case 1: 
    return '已参与' 
  case 2: 
    return '已猜中' 
}
// 这里用object来映射关系，扩展性好，不受key改变调整数据结构
const TypeObjMap = {
  0: '未参与',
  1: '已参与',
  2: '已猜中'
}

// 这里用array来映射关系，受索引来映射关系，如果key改为字符串则需要转换数据格式
const TypeArrMap = ['未参与', '已参与', '已猜中']

const typeText = TypeObjMap[type]
const typeText2 = TypeArrMap[type]


// 错误示范
if (type === 0) { 
  return '未参与' 
} else if (type === 1) { 
  return '已参与 
} else if (type === 2) { 
  return '已猜中' 
} 
// 最佳示范
switch (type) { 
  case 0: 
    return '未参与' 
  case 1: 
    return '已参与' 
  case 2: 
    return '已猜中' 
}

遇到多参数入参，建议三个及以上的入参用对象传参

ts
function track(event: string, pageName: string) {}
function track(event: string, pageName: string, params: Record<string, any>) {}
function track(params: Record<string, any>) {}
function track(event: string, pageName: string) {}
function track(event: string, pageName: string, params: Record<string, any>) {}
function track(params: Record<string, any>) {}

页面跳转统一用Cix.to

【特别注意】这里的page前必须加斜杆"/"，如/pages

ts
import Cix from '@/cix/proxy/Cix'
const toDetail = () => {
  Cix.to('/pages/detail/index')
}
import Cix from '@/cix/proxy/Cix'
const toDetail = () => {
  Cix.to('/pages/detail/index')
}

非必要的调试代码必须删除

ts
console.log(123, data) 
console.log('-----', data) 
console.log('data', data) 
console.log(123, data) 
console.log('-----', data) 
console.log('data', data)

git提交规范 ​

【建议】

ts
// commitlint.config.js
...
  [
    "feat", // 新功能
    "fix", // 修复bug
    "style", // 修改格式，删除代码空格、缩进等
    "docs", // 文档、注释修改
    "refactor", // 代码重构，没有功能修改
    "merge", // 代码合并
    "revert", // 版本回滚
    "chore", // 构建过程或辅助工具的变动
    "test", // 测试代码
    "types", // 更新类型
    "release", // 发布版本
    ...
  ]

  // 例如，...是指页面下的模块
  git commit -m "feat: 新增了...功能"     // 新功能
  git commit -m "fix: 指数选基..."        // bug修复
  git commit -m "style: 指数选基..."      // 样式修改
  git commit -m "test: 测试指数选基..."   // 测试代码
...
// commitlint.config.js
...
  [
    "feat", // 新功能
    "fix", // 修复bug
    "style", // 修改格式，删除代码空格、缩进等
    "docs", // 文档、注释修改
    "refactor", // 代码重构，没有功能修改
    "merge", // 代码合并
    "revert", // 版本回滚
    "chore", // 构建过程或辅助工具的变动
    "test", // 测试代码
    "types", // 更新类型
    "release", // 发布版本
    ...
  ]

  // 例如，...是指页面下的模块
  git commit -m "feat: 新增了...功能"     // 新功能
  git commit -m "fix: 指数选基..."        // bug修复
  git commit -m "style: 指数选基..."      // 样式修改
  git commit -m "test: 测试指数选基..."   // 测试代码
...

如何命名 ​

这里提供几个思路

  • 意义（名称应该与被命名的对象或概念相关联）
  • 形状（名称可以基于对象的形状、特征或外观）
  • 独特性（不易与其他名称混淆的名称）

lhiro

Copyright © 2002-present Evan investoday