原有vue项目接入typescript

作者 | 陈龙

为什么要接入typescript

javascript由于自身的弱类型，使用起来非常灵活。

这也就为大型项目、多人协作开发埋下了很多隐患。如果是自己的私有业务倒无所谓，主要是对外接口和公共方法，对接起来非常头疼。主要表现在几方面：

1. 参数类型没有校验，怎么传都有，有时会出现一些由于类型转换带来的未知问题。

2. 接口文档不规范，每次都要通过读代码才能知道传什么，怎么传

3. 接口编写符合规范，但是公共库中有大量的处理类型校验的代码

这就非常不利于工程标准化。于是我们决定引入typescript进行代码层面的强校验。

概览

原有vue项目接入ts主要包含下面几大步骤：

1. 安装typescript相关npm包

2. 修改webpack和ts配置文件

3. 项目公共库和vue文件改造

ok，我们开始

1. 安装typescript相关npm包

这块有个非常重要的点需要注意：

就是要根据你本地的环境，去升级对应版本的typescript

这块是很多初次使用的同学都会遇到的问题。

因为只是看到了官网的教程，一步一步安装完发现各种报错。主要问题就是webpack版本不匹配，或者其他一些npm包版本不匹配

以我本地为例：

我本地环境是webpack3，所以直接安装最新版本的typescript，控制台会报错webpack版本过低的问题。

所以你要不把自己的webpack升级到webapck4.要不就采用与之相匹配的typescript版本。

我选择的是后者，因为直接给自己的项目升级到webapck4，会花费更长的时间。我们用的脚手架是公司内部统一的。里面集成了很多底层通用的基础服务。冒然升级webpack4会带来更大的麻烦，更何况项目时间比较紧迫，你懂得。

下面是我安装的包和对应的版本：

• "typescript": "^3.1.4" (这个是必须的，ts库)

• "ts-loader": "^3.5.0" (识别ts的laoder)

• "tslint": "^5.11.0" (tslint校验库)

• "tslint-loader": "^3.5.4" (tslint的loader)

• "tslint-config-standard": "^8.0.1" (用于tslint默认校验规则)

• "vue-property-decorator": "^7.2.0" (用于在.vue文件中使用ts语法)

2. 修改配置文件

• 修改webpack配置文件（加入ts的相关配）

1. base: {

2.  entry: {

3.    ...

4.    app: resolve('src/main.ts') // 把main.js改为main.ts

5.  }

6. ...

7. resolve: {

8.  ...

9.  extensions: ['vue', '.js', '.ts']

10. }

11. module: {

12.  rules: [

13.    ...,

14.    {                           // 加入对文件的ts识别        

15.      test: /\.ts$/,

16.      exclude: /node_modules/,

17.      enforce: 'pre',

18.      loader: 'tslint-loader'

19.    }, {

20.      test: /\.tsx?$/,

21.      loader: 'ts-loader',

22.      exclude: /node_modules/,

23.      options: {

24.        appendTsSuffixTo: [/\.vue$/],

25.      }

26.    }

27.  ]

28. }

注意： main.js改成main.ts后，还要做一些改造，这个比较简单，按照tslint的错误提示改就可以了

• 在根目录下创建tslint.json（类似eslint，这里设定一个校验标准）

1. {

2.  "extends": "tslint-config-standard",

3.  "globals": {

4.    "require": true

5.  }

6. }

• 在根目录创建tsconfig.json（typescript配置文件）

1. {

2.  "compilerOptions": {

3.    // 编译目标平台

4.    "target": "es5",

5.    // 输出目录

6.    "outDir": "./dist/",

7.    // 添加需要的解析的语法，否则TS会检测出错。

8.    "lib": ["es2015", "es2016", "dom"],

9.    // 模块的解析

10.    "moduleResolution": "node",

11.    // 指定生成哪个模块系统代码

12.    "module": "esnext",

13.    // 在表达式和声明上有隐含的any类型时报错

14.    "noImplicitAny": false,

15.    // 把 ts 文件编译成 js 文件的时候，同时生成对应的 map 文件

16.    "sourceMap": true,

17.    // 允许编译javascript文件

18.    "allowJs": true,

19.    // 指定基础目录

20.    "baseUrl": "./",

21.    // 启用装饰器

22.    "experimentalDecorators": true,

23.    // 移除注释

24.    "removeComments": true,

25.    "pretty": true,

26.    // 是相对于"baseUrl"进行解析

27.    "paths": {

28.      "vue": ["node_modules/vue/types"],

29.      "@/*": ["src/*"]

30.    }

31.  },

32.  "include": [

33.    "src/**/*"

34.  ],

35.  "exclude": [

36.    "node_modules"

37.  ]

38. }

• 在src目录下创建sfc.d.ts（用来声明全局变量、class、module、function、命名空间）

我们在这里主要是让ts识别.vue文件、window对象和一些module

具体declare的使用方式请看这里 (https://www.tslang.cn/docs/handbook/declaration-files/by-example.html)

1. /**

2. * 告诉 TypeScript *.vue 后缀的文件可以交给 vue 模块来处理

3. * 而在代码中导入 *.vue 文件的时候，需要写上 .vue 后缀。

4. * 原因还是因为 TypeScript 默认只识别 *.ts 文件，不识别 *.vue 文件

5. */

6. declare module "*.vue" {

7.  import Vue from 'vue'

8.  export default Vue

9. }

10. /**

11. * 告诉 TypeScript window是个全局对象，直接可用，这样就不会在window.xx = 123时报错

12. */

13. declare var window: any

14. /**

15. * 引入部分第三方库/自己编写的模块的时候需要额外声明文件

16. * 引入的时候，需要使用类似 import VueLazyLaod from 'vue-lazyload' 的写法

17. */

18. declare module 'vue-lazyload'

19. declare module '@zz/perf/vue'

20. declare module 'raven-js'

21. declare module 'raven-js/plugins/vue'

将src/main.js改为main.ts

项目改造

这个部分是最麻烦的，主要有几大块

• 基础库改造

如果你的基础库引用了大量的npm包，那么恭喜你，这部分你的改造成本会低很多。

如果你的lib库有相当一部分都是自己手写的，那么，我也得恭喜你。。。

我们自己的lib库里，有大量的自己维护的js文件。那么如果你要进行ts改造的话，通通都要改。

举个例子： lib/url.js 中的getParam (算法并不高级，就是易读、兼容性好)

1. export default class URL{

2.  /**

3.   * @memberOf URL

4.   * @summary 获取当前页面连接中指定参数

5.   * @type {function}

6.   * @param {string} param1                     - 如果param2为undefined，param1是指从当前页面url中获取指定参数的key, 如果param2不为空，param1为指定的url

7.   * @param {string} param2                     - 可选参数，如果param2存在，则从指定的param1连接中获取对应参数的key

8.   * @return {string|null}

9.   */

10.  static getParam (param1, param2) {

11.    let url = ''

12.    let param = null;

13.    // 如果只有一个参数，默认从当前页面链接获取参数

14.    if (typeof param2 === 'undefined') {

15.      url = window && window.location.href || ''

16.      param = param1

17.    // 从指定url中获取参数

18.    } else {

19.      url = param1

20.      param = param2

21.    }

22.    // 排除hash的影响

23.    url = url.split('#')[0]

24.    if (url.indexOf('?') > -1) {

25.      url = url.split('?')[1]

26.    }

27.    const reg = new RegExp('(^|&)' + param + '=([^&]*)[&#$]*', 'i')

28.    const rstArr = url.match(reg)

29.    if (rstArr !== null) {

30.      return decodeURIComponent(rstArr[2])

31.    }

32.    return null

33.  }

34.  ...

35. }

改造后的文件为：lib/url.ts

1. export default class URL {

2.  /**

3.   * @memberOf URL

4.   * @summary 获取url中指定参数

5.   * @type {function}

6.   * @param {string} param1                     - 如果param2为undefined，param1是指从当前页面url中获取指定参数的key, 如果param2不为空，param1为指定的url

7.   * @param {string} param2                     - 可选参数，如果param2存在，则从指定的param1连接中获取对应参数的key

8.   * @return {string|null}

9.   */

10.  static getParam (param1: string, param2?: string): string {

11.    let url: string = ''

12.    let param = null

13.    // 如果只有一个参数，默认从当前页面链接获取参数

14.    if (typeof param2 === 'undefined') {

15.      url = window && window.location.href || ''

16.      param = param1

17.    // 从指定url中获取参数

18.    } else {

19.      url = param1

20.      param = param2

21.    }

22.    url = url.split('#')[0]

23.    if (url.indexOf('?') > -1) {

24.      url = url.split('?')[1]

25.    }

26.    const reg = new RegExp('(^|&)' + param + '=([^&]*)[&#$]*', 'i')

27.    const rstArr = url.match(reg)

28.    if (rstArr !== null) {

29.      return decodeURIComponent(rstArr[2])

30.    }

31.    return null

32.  }

33.  ...

34. }

对于一个方法多种调用方式，如果你想完全改成typescript推荐的方式，你可以用到方法重载。(https://www.tslang.cn/docs/handbook/functions.html)

我没有用是因为我不希望改变原有页面的使用方式。

注：对于一个大型项目来讲，我们并不建议上来就对全部的文件进行ts改造。

我们更建议采用渐进式改造方案，在不影响原有页面的情况下，逐一改造。具体方案后面会介绍

• vue文件改造

src/components/helper/newUser/index.vue

3. lang="scss" scoped>...

改造后

2. lang="ts">

3. import { LEGO_ATTR, initLegoData, legic } from '@/lib/legic'

4. import { getMyProfile } from '@/api/helper.ts'

5. import { toast } from '@/lib/ZZSDK'

6. import { Component, Vue } from 'vue-property-decorator'

7. import test from './test.vue'

9. let flag: boolean = false // 是否发送视频点击埋点

10. @Component({

11.  components: {

12.    test

13.  }

14. })

15. export default class NewUser extends Vue {

16.  // 用户头像

17.  portrait = ''

18.  // 用户名称

19.  nickName = ''

20.  // 是否点击播放

21.  isPlay = false

23.  mounted (): void {

24.    this.initData()

25.    initLegoData({

26.      type: 'newUserGuide'

27.    });

28.    legic(LEGO_ATTR.newUserGuide.SHOW)

29.  }

31.  initData () {

32.    // 获取profile信息

33.    getMyProfile().then((data: any) => {

34.      console.log('data', data)

35.      const { respData } = data

36.      this.portrait = respData.portrait || ''

37.      this.nickName = respData.nickname || ''

38.    }).catch((err: string) => {

39.      toast({ msg: err })

40.    })

41.  }

43.  goPageClick (type: string) {

44.    switch (type) {

45.      case 'SUN':

46.        legic(LEGO_ATTR.newUserGuide.SUNVILLAGECLICK)

47.        break

48.      case 'FOOTBALL':

49.        legic(LEGO_ATTR.newUserGuide.FOOTBALLCLICK)

50.        break

51.      case 'SIGN':

52.        legic(LEGO_ATTR.newUserGuide.SIGNCLICK)

53.        break

54.      default:

55.        return

56.    }

57.  }

59.  videoClick () {

60.    if (flag) {

61.      return

62.    } else {

63.      flag = true

64.      legic(LEGO_ATTR.newUserGuide.SIGNCLICK)

65.      this.isPlay = true

66.      this.$refs.video['play']()

67.    }

68.  }

69. }

71. lang="scss" scoped>...

myComponent.vue改造前略，这里只展示改造后的组件

2. lang="ts">

3. import { Component, Prop, Vue } from 'vue-property-decorator'

5. @Component

6. export default class MyComponent extends Vue {

8.  @Prop({ type: String, default: '' })

9.  name: string

11.  title: string = '您好'

12. }

14. lang="scss" scoped>

15.  .main{

16.    display: none;

17.  }

这里需要注意的是：

• ts默认不会识别.vue文件，所以需要在sfc.d.ts文件中声明，同时在引入vue组件时，要加.vue后缀

• 引入vue-property-decorator插件。采用修饰符的方式进行组件注册，这样里面的data、prop和function都通过扁平化方式调用（这也是官方推荐的方式）

• ts中import引入文件，如果不写后缀，默认是js文件。如果js文件没有，则才识别ts文件

现在说下前面提到的改造方案：

这里其实主要涉及.vue文件和lib库的改造，vue文件没啥可说的，一个个改就可以了。主要说lib里面的文件，这里我建议：

• 一开始保留原来的js文件，并不删除。这样目前尚未改造的文件可以继续使用

• 新建对应的ts文件，比如lib中有util.js，新创建util.ts

• 新改造的vue文件通通引入lib库中xx.ts（要加.ts后缀）,如import Util from '@/lib/util.ts' 这样可以一点点改造整个项目，同时未改造的页面照样可以运行。

ok以上就是我们改造的全部过程。 有什么问题可以指正，大家互相学习