Vue + TypeScript Web应用实践

项目各类代码规范作用详见小白项目规范最佳实践一文

项目创建

使用@vue/cli脚手架的vue-ui创建项目。

• 创建过程中需要注意的点:

  • 开启TypeScript，关闭class-style component syntax，开启该功能会引入vue-property-decorator依赖，在vue-ts项目中，通过使用@Component等装饰器来简化书写。习惯于使用装饰器等语法可选择使用。

  • 使用dart-sass作为CSS与处理器

  • 不使用脚手架提供的自动配置eslint，后续手工添加配置

  • 开启PWA Support

VSCode插件添加

• Prettier、ESLint、stylelint、Vetur

Prettier配置

• 配置.prettierrc以规范代码风格，配置内容如下。配置完成后，vscode开启配置，通过Prettier插件在保存文件时，自动完成代码格式化。

  {
    "tabWidth": 2, // 缩进空格为2，
    "useTabs": false, // 不使用Tab作为缩进
    "printWidth": 100, // 单行代码最多字符数，将vscode单屏可视部分作为最大长度即可
    "semi": true, // 使用分号
    "singleQuote": true, // 字符串单引号
    "arrowParens": "avoid", // 单入参箭头函数可不带括号
    "trailingComma": "all", // 对象属性后添加逗号
    "bracketSpacing": true, // 括号前后增加括号
    "jsxSingleQuote": true,
    "jsxBracketSameLine": false,
    "insertPragma": false,
    "ignorePath": ".prettierignore" // ignore文件对应路径
  }

ESLint配置

• Vue部分正常配置即可，重点关注TypeScript部分的配置

  • 增加以下两个依赖

  $ yarn add -D @typescript-eslint/parser
  $ yarn add -D @typescript-eslint/eslint-plugin

  • 在.eslintrc.js中增加以下配置

    module.export = {
      // ...
      parserOptions: {
        parser: '@typescript-eslint/parser', // TypeScript parser
        ecmaVersion: 8, // ES版本
        project: ['./tsconfig.json'], // tsconfig路径
      },
      plugins: ['@typescript-eslint'], // 启用typescript-eslint插件
      extends: [
        // ...
        'plugin:@typescript-eslint/recommended',
        '@vue/typescript/recommended',
      ],
      rules: {
        // ...
        '@typescript-eslint/no-explicit-any': 'error', // 显式any类型定义报错
        '@typescript-eslint/no-unused-expressions': ['error'], // 未使用变量报错
      },
    }

  • 由于使用@vue/cli构建项目时，已开启TypeScript，直接使用脚手架创建的tsconfig.json即可，但由于项目中同样存在js文件，所以需要增加js配置，来保证typescript-eslint也能够对js文件生效。

    {
      ...
      "include": [
        "*.js", // 增加js配置
        ".eslintrc.js"
      ],
    }

  • vscode安装ESLint插件后，在右下角开启ESLint检测，运行项目后，若有ESLint运行报错，根据报错内容解决即可。若为代码格式报错，保存后即可实现代码自动规范。保存自动规范需要通过配置vscode设置文件setting.json开启。之后ESLint正常开启检测。

    {
      "editor.formatOnPaste": true,
      "editor.formatOnType": true,
      "eslint.codeAction.showDocumentation": {
          "enable": true
      },
      "editor.codeActionsOnSave": {
          "source.fixAll": true
      },
      "[javascript]": {
          "editor.defaultFormatter": "esbenp.prettier-vscode"
      },
      "[vue]": {
          "editor.defaultFormatter": "esbenp.prettier-vscode"
      }
    }

stylelint配置

配置stylelint实现样式代码的规范化。

• 安装依赖

  • stylelint

    $ yarn -D stylelint stylelint-config-stylelint

  • scss插件

    $ yarn -D stylelint-scss

  • 样式规则排序

    $ yarn -D stylelint-order

• 增加stylelint配置

  // .stylelintrc.js
  module.exports = {
    extends: 'stylelint-config-standard',
    plugins: [
      'stylelint-order',
      'stylelint-scss',
    ],
    rules: {
      'color-no-invalid-hex': true, // 禁止无效十六进制颜色
      'property-no-unknown': true, // 禁止unknown属性
      'string-no-newline': true, // 禁止字符串类属性换行
      'unit-no-unknown': true, // 禁止unknown样式单位
      'order/order': [
        'declarations',
        'custom-properties',
        'dollar-variables',
        'rules',
        'at-rules'
      ],
      'order/properties-order': [
        // 自定义样式规则顺序
      ]
    }
  }

• 上述配置中，order/order中的顺序样例

  a {
    /* declaration */
    --width: 10px;
    /* custom-properties */
    $height: 20px;
    /* dollar-variables */
    display: none;
    /* rules */
    span {}
    /* at-rules */
    @media (min-width: 100px) {}
  }

• stylelint至此已经能够正确生效。

Lint-staged配置

通过lint-staged在代码commit前对代码规范进行检测，防止非规范代码递交。

• 安装husky

  $ yarn add -D husky

• husky能够为git增加git hook，使我们可以在对应的钩子下增加我们需要的命令，lint-staged的功能就是在pre-commit这个钩子的阶段，增加对暂存区代码规范性的检测，防止不符合代码规范的代码进行递交。

• pre-commit配置与验证，package.json增加pre-commit的git-hook

  "husky": {
    "hook": {
      "pre-commit": "echo \"git commit trigger husky pre-commit hook\" "
    }
  }

• commit本地更新后，pre-commit成功触发

  
• 安装lint-staged

  yarn add -D lint-staged

• package.json增加lint-staged的配置用于检测ts与vue文件，并在pre-commit中增加lint-staged执行命令

  "husky": {
    "hook": {
      "pre-commit": "lint-staged "
    }
  },

• 新增lint-staged配置文件

  // lint-staged.config.js
  module.exports = {
    'src/**/*.{ts,vue}': filenames => {
      return [
        'eslint --cache --quiet',
        'prettier --write',
        'stylelint src/**/*.{html,vue,css,sass,scss} --fix', // stylelint检测
      ];
    },
  };

• 对lint-staged功能进行验证。设置vscode，关闭on save时的代码自动格式化，编写一行不符合格式规范的代码，这里使用不带分号的代码进行验证。

  // main.ts
  import Vue from 'vue' // 无分号

• commit代码触发pre-commit中的lint-staged命令，代码被prettier与eslint自动格式化，原无分号的代码已经自动增加分号

  

  // main.ts
  import Vue from 'vue';

lint-staged tsc

在lint-staged中增加TypeScript的检测