支持 Typescript 和 JSX #

在 Vue 中开启 Typescript 和 JSX 支持并不是一件容易的事情 。 因此我们单独出一份文档来说明一下。

依赖 #

如果你想要使用 TSX / JSX 开发，并且获取到更好的 Typescript 类型检查，需要安装以下依赖:

$ pnpm add babel-preset-wakeadmin @wakeadmin/h @wakeadmin/demi vue-tsc -D
# 升级 @wakeadmin/* 相关依赖到最新版本
$ pnpm up -r -L \"@wakeadmin/*\"

• babel-preset-wakeadmin 使用 react jsx 的标准语法来转换 JSX。
• @wakeadmin/h 更好地支持 react-jsx 的标准 JSX 语法，没有语法糖，更接近 React 的开发体验。兼容 Vue 2/3。详见 下文
• @wakeadmin/demi fork from vue-demi , 修复了一些问题。可以完全取代 vue-demi
• vue-tsc Volar 底层依赖的 Typescript 编译器。这里主要用于类型检查

构建 #

首先根据你使用的构建工具，配置相关的 Typescript 构建支持：

• Vite : 内置支持转换 , 但是类型检查需要借助 vue-tsc
• Vue CLI : 卸载掉 @vue/cli-plugin-typescript , 并安装 @wakeadmin/vue-cli-plugin-typescript 。这个插件底层基于 esbuild 进行编译， 不会进行类型检查 , 因此还是需要借助 vue-tsx , 详见 下文 。

配置 #

接着配置 tsconfig.json:

{
  "compilerOptions": {
    "types": ["@wakeadmin/demi"]
  // 如果是 vue 2, 则加上以下配置
  "vueCompilerOptions": {
    "target": 2.7,
    // 转换 template 为 jsx 模式，目前而言好处就是检查更加严格, 而且对泛型组件的支持较好
    "jsxTemplates": true

接着，配置一个 src/env.d.ts (旧的项目可能已存在, 比如 vue-cli, shims-tsx.d.ts 、 shims-vue.d.ts , 将这些文件删掉) 文件，让 TypeScript 标准 的类型检查器可以识别 *.vue 文件:

// env.d.ts
// 你可能把旧的 declare module '*.vue' 移除
declare module '*.vue' {
  import type { DefineComponent } from 'vue';
  const component: DefineComponent<{}, {}, any>;
  export default component;

IDE 类型提示 #

IDE 上推荐使用 Valor 插件，并 禁用掉 Vetur 插件 。在 VSCode 中, 你可以安装一下两个插件:

• Vue Language Features : Vue, Vitepress, petite-vue language support extension for VSCode
• TypeScript Vue Plugin VSCode extension to support Vue in TS server

开启类型检查 #

最后，如果想要对类型进行检查，推荐使用 vue-tsc :

// package.json
  "scripts": {
    "prebuild": "vue-tsc --noEmit"

如果使用了惟客云 自动化检查工具 , 可以这样配置：

// .standard.jsonc
  // 执行 Typescript 类型检查
  "typescriptEnable": true,
  // typescript 检查命令
  "typescriptCmd": "vue-tsc --noEmit"

更好地支持 JSX/TSX #

大部分场景，我们推荐你使用 Vue 的 SFC + setup + TypeScript 来编写组件。

然而，在你们使用 @wakeadmin/components 时，为了灵活定义组件库，你会经常用到 JSX。

假设你的项目使用是 Vue-cli, 第一步先修改 babel.config.js

module.exports = {
  // 关闭 vue 默认的 jsx 转换， 统一使用标准的 JSX
  presets: [['@vue/cli-plugin-babel/preset', { jsx: false }], 'babel-preset-wakeadmin'],

接着修改 tsconfig.json 配置:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@wakeadmin/h",
    "types": ["@wakeadmin/demi"],

这里，我们使用 @wakeadmin/h 来编写 JSX。好处是：

1. 不管你用的是 Vue 2, 还是 Vue 3, 使用 @wakeadmin/h 可以提供一致的编写方式 , 更接近我们在 React 上的使用习惯。

   • Vue 2 / 3 JSX 书写上 相差非常大
   • Vue 官方的 JSX 库携带了很多语法糖。这依赖于 Babel 的转换，这意味着你无法直接使用 esbuild、Typescript 这类工具进行编译。

2. 除此之外， @wakeadmin/h 也优化了 Vue JSX 在 Typescript 支持上的一些问题。

使用示例：

<div onClick={handleClick} class="hello" />; // 使用 on* 的语法进行事件监听
<div onClick={handleClick} class={[hello, { active: isActive }]} style={{ color: 'red' }} />;
// 插槽的使用，使用 v-slots
<Tooltip v-slots={{ content: <div>hello</div>, named: scope => <div>命名插槽</div> }}>
  <span class="fat-actions__btn">{content}</span>
</Tooltip>;
// 指令：https://vuejs.org/api/render-function.html#withdirectives
<div {...withDirectives([[vLoading, loading.value]])}>加载中</div>;

ESLint 适配 #

你可以使用 wkstd init 来初始化 eslint 的配置, 典型的 ESlint 配置如下：

module.exports = {
  extends: ['wkts', 'wkvue'],
  plugins: [],
  globals: {},
  rules: {
    'vue/no-deprecated-slot-attribute': 




    
'off',
  parser: 'vue-eslint-parser',
  // 为了支持 Typescript 需要配置 '@typescript-eslint/parser'
  parserOptions: {
    parser: '@typescript-eslint/parser',
    project: 'tsconfig.json',
    sourceType: 'module',
    ecmaVersion: 'latest',
    extraFileExtensions: ['.vue'],
  env: {
    browser: true,
    es2020: true,
  // 检查 .tsx/.ts 文件
  overrides: [
      files: ['*.ts', '*.tsx'],
      rules: {
        // 使用 typescript 检查
      parser: '@typescript-eslint/parser',
      parserOptions: {
        warnOnUnsupportedTypeScriptVersion: true,
        ecmaVersion: 'latest',
        lib: ['esNext'],
        project: './tsconfig.json',

然而可能不会像你想象的那么顺利。

// 支持 .vue 文件中 包含 jsx
const ts = require('typescript');
const { ensureScriptKind } = ts;
ts.ensureScriptKind = function (fileName, ...args) {
  if (fileName.endsWith('.vue')) {
    return ts.ScriptKind.TSX;
  return ensureScriptKind.call(this, fileName, ...args);
module.exports = {
  extends: ['wkts', 'wkvue'],
  // ....  eslint 配置

老项目中启用 TypeScript #

老项目(假设是 Vue 2)中也可以按照上文的配置开启 Typescript。有以下几个要点

• 开启 tsconfig.json 的 allowJS, 而不是 checkJS。这表示允许和 Javascript 混用，但不检查 Javascript。如果开启 checkJS 可能有成吨的异常抛出来。

• 如何扩展 Vue 的类型？比如全局方法、全局对象、全局组件等等。 Vue 2/3 定义方式有点区别， 这里展示 Vue 2 的使用方式 ，你也可以参考相关的第三方库。以 vue-router 为例

  扩展全局组件实例成员:

  typescript

  declare module 'vue/types/vue' {
    interface Vue {
      $router: VueRouter;
      $route: Route;
  

  扩展 optional API

  ts

  declare module 'vue/types/options' {
    interface ComponentOptions<V extends Vue> {
      router?: VueRouter;
      beforeRouteEnter?: NavigationGuard<V>;
      beforeRouteLeave?: NavigationGuard<V>;
      beforeRouteUpdate?: NavigationGuard<V>;
  

  扩展全局组件:

  ts

  declare module 'vue' {
    export interface GlobalComponents {
      RouterLink: typeof import('vue-router')['RouterLink'];
      RouterView: typeof import('vue-router')['RouterView'];
  

element-ui 同理：

// 注意 element-ui 类型基本上是残废的，无法正常推断 props 类型
declare module 'vue' {
  import element from 'element-ui';
  type TypeofElementExpose = typeof element;
  type KeyOfElementExpose = keyof TypeofElementExpose;
  type KeyofComponent = Exclude<KeyOfElementExpose, 'version' | 'install'>;
  type ElementComponents = {
    [K in KeyofComponent as `El${K}`]: TypeofElementExpose[K];
  export interface GlobalComponents extends ElementComponents {
    RouterView: typeof import('vue-router').RouterView;