niuhe 插件官方教程

生成 typescript api 定义

在开发前端应用时，通常需要根据后端的 API 接口定义来生成相应的 TypeScript 类型。niuhe 插件提供了便捷的方式来自动生成这些类型定义文件。以下是如何生成 TypeScript API 定义的步骤：

1. 添加 ts 语言支持

首先，在 docs/.config.json5 的 langs 中添加 ts。生成代码后会生成如下几个文件:

typings
├── api.ts - API 接口类型定义
├── event.d.ts - 部分公共属性定义
├── request.ts - 请求方法封装
└── types.d.ts - niuhe 中定义的类型定义

2. 自定义 typescript 配置

上述生成的四个文件中 event.d.ts 和 request.ts 和 内容是不会变的, 将其复制到目标位置即可。api.ts 和 types.d.ts 需要根据实际情况进行调整。因此在 docs/.config.json5 需要根据项目需要修改 typescript 配置。 typescript 定义如下:

interface TsConfig {
    app: string
    modes: string[]
    types: string[]
    api: string[]
    enumjs: string[]
    optional: boolean
    tsenum: boolean
}
interface EntryInfo {
    app: string // 项目名
    ...
    typescript: TsConfig[] // ts 相关配置, 在 langs 中添加 ts 时生效
    ...
}

参数说明:

• app 生成 ts 代码中的 app 名, 不定义则保持同项目同名
• modes 生成对应的 mode, 如有 api(前端网页项目) 和 admin(后台管理项目) 两个 mode, 则可根据需要最小化生成代码。
• types types.d.ts 存储路径, 支持相对路径和绝对路径, 支持多个
• api api.ts 存储路径, 支持相对路径和绝对路径, 支持多个
• enumjs js 版枚举类型定义, 需要在入口文件中引入, 如在 main.ts 中引入 import './enum.js'
• optional niuhe 中定义的 optional 定义的参数生成代码时否生添加 ?, 默认值为 false
• tsenum types.d.ts 的 interface 中字段为枚举时是否声明为对应枚举类型, 默认值为 false。当前是转为 int/string

引入 enumjs 配置项原因: 在 types.d.ts 中定义的 enum 在代码中引用时编辑器和编译器都不会报错。但是在运行时会报 is undefined 错误。此时需要在 window 中挂载对应枚举值即可修复, 引入此配置项即解决此问题。

其他实现方案

通过插件的 template 能力, 也可自行定义 typescript 形式, 具体参考模板库中 typescript enum、typesctipt api、typescript interface 三个例子。