使用TypeScript开发kintone自定义

aki发表于:2020年10月23日 12:53:58更新于:2021年09月01日 14:09:20

概要

不知道大家是否有同感,像JavaScript这种在执行时决定数据类型的开发语言,随着代码量的增加,维护越来越难。

为了解决这个问题,诞生了TypeScript这个语言。

本文将介绍如何使用TypeScript自定义kintone。

什么是TypeScript

TypeScript是Microsoft开发的JavaScript的扩展语言。

TypeScript的主要功能之一是检查静态类型。

TypeScript虽是JavaScript的扩展语言,但可将类型信息嵌入程序内。

通过编译(即将TypeScript转换成JavaScript的处理)对类型进行检查。

类型检查失败时,TypeScript转换成JavaScript的处理也失败。

只要在程序内适当加入类型信息,即可对代码可读性以及类型等进行检查,

在编写大规模代码时,可以更加轻松地编写易于维护的代码。

关于TypeScript的详细语法和转换情况等,请参考官网的文档。

参考: TypeScript in 5 minutes ,TypeScript PlaygroundTypeScript Deep Dive

 

最后再跟大家分享一个好消息,VSCode以及InitelliJ IDE(IDEA,Webstorm) 等可以获得TypeScript类型信息的强大补全功能。

关于代码的补全,会在本文最后附上GIF动画,感兴趣的同学请注意查看。

 关于前提知识

本文用到了Webpack和Babel,如您对Webpack完全不了解,请先阅读Webpack入门

另外,实际开发过程中,不要单靠TypeScript进行类型检查,推荐结合ESLint以及Prettier等静态解析工具一起使用。

本文在使用TypeScript开发kintone自定义(日语)基础上进行改编而成。

 

入门教程

本入门教程是使用TypeScript进行简单的kintone自定义。

※ Windows(Powershell)环境下,换行前的转义符号[ \(反斜杠) ] 要换成 [ `(重音符号)]。

 目录的结构如下:

 $ tree -I node_modules    
.    
├── babel.config.js                   # babel的设置文件    
├── dist                              # webpack的编译结果    
│   └── kintone-typescript-sample.js    
├── package-lock.json    
├── package.json    
├── src    
│   ├── fields.d.ts                   # 用@kintone/dts-gen生成的类型信息    
│   └── kintone-typescript-sample.ts  # 自定义的入口点    
├── tsconfig.json                     # TypeScript编译设置    
└── webpack.config.js                 # webpack设置文件

准备自定义时要用的kintone应用

为了方便大家快速进入自定义步骤,本次为大家准备好了应用的模板,关于使用模板创建应用的方法,请参考帮助手册

初始化项目

初始化项目,并安装使用TypeScript进行kintone开发所需要的工具。

npm init
npm install -D @kintone/dts-gen \
                         @babel/core @babel/plugin-proposal-class-properties \
                         @babel/preset-env \
                         @babel/preset-typescript \
                         babel-loader \
                         fork-ts-checker-webpack-plugin \
                         typescript \
                         webpack \
                         webpack-cli
  • @kintone/dts-gen ... kintone自定义开发时所需要的工具

  • @babel~~ .... 代码转换工具

  • fork-ts-checker-webpack-plugin ... 在webpack进行编译时检查类型的工具

  • typescript ... TypeScript编译器

  • webpack,webpack-cli ... 编译工具

根据kintone应用的字段信息生成类型信息

@kintone/dts-gen中绑定的命令行工具,除了可对kintone的JavaScript自定义的函数进行自定义之外,还可获取所指定的应用的字段信息。

# npx @kintone/dts-gen ... 也可以
# 会生成kintone.types.Fields, kintone.types.SavedFields保存到fields.d.ts
npx @kintone/dts-gen --base-url https://***.cybozu.cn \
                                    -u username \
                                    -p password \
                                    --app-id 12
  • --base-url ... 要进行自定义的URL

  • -u ... 用户名

  • -p ... 密码

  • --app-id ... 要进行自定义的ID

  • --type-name ... 要生成的类型名称(未指定时默认Fields)

    • 已保存的类型生成为SavedFields,未保存的类型生成为Fields

  • --namespace ... 要输出的命名空间 (未指定时默认kintone.types)

  • -o ... 要输出的文件名(未指定时默认fields.d.ts)

上面的例子中,执行之后会根据kintone的字段信息生成 一个文件名为fields.d.ts的类型定义文件。
如更新了kintone的字段信息,需要重新生成类型信息。
请将生成的field.d.ts移到src目录下。

创建webpack.config.js

 webpack.config.js的例子:

const path = require('path');
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  entry: {
    "kintone-typescript-sample" : "./src/kintone-typescript-sample.ts"
  },

  output: {
    filename: '[name].js',
    path: path.resolve(__dirname, 'dist'),
  },

  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.json']
  },

  module: {
    rules: [{ test: /\.(ts|js)x?$/, loader: 'babel-loader', exclude: /node_modules/ }],
  },

  plugins: [
    new ForkTsCheckerWebpackPlugin(),
  ]
};

设置文件的模板请参考 webpack-typescript-babel(github) 的webpack.config.js。

创建tsconfig.json

tsconfig.json的例子

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "esModuleInterop": true,
    "noUnusedLocals": true,
    "noImplicitAny": true,
    "declarationDir": "dist/types",
    "declaration": true,
    "target": "es5",
    "module": "es2015",
    "strict": true
  },
  "files" : [
    "./node_modules/@kintone/dts-gen/kintone.d.ts",
    "./src/fields.d.ts"
  ],
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "dist",
    "node_modules"
  ]
}

files ... 指定要编译的文件。通过事先指定类型信息文件,可避免在编译的时候发生函数未定义的错误。

includes ... 包含编译文件。和files进行比较时,可使用*等glob方法。

excludes ... 指定的文件不包含编译文件。

在"files"中添加入门教程中生成的类型定义文件和kintone上可使用的函数定义文件(kintone.d.ts)。

TypeScript编译器在进行类型检查时会读取设置文件,检查是否按照类型定义文件进行编码。

设置方法除了上述之外,还有写3遍斜杆的写法,如要使用这种写法,请参考TypeScript的官网。

设置文件的模板参考了 webpack-typescript-babel(github) 的tsconfig.json。其他详细设置,请参考TypeScript官网文档。

创建Babel的设置文件 

babel.config.js的例子

module.exports = function (api) {
    api.cache(true);
    const presets = [
        [
            "@babel/preset-env",
            {
              "useBuiltIns": "entry",
              "corejs": 3,
            }
        ],
        "@babel/typescript"
    ];
    const plugins = [
        [
            "@babel/proposal-class-properties"
        ]
    ];
    return {
        presets,
        plugins,
    }
}

本入门教程使用TypeScript进行类型检查。

程序转换为ES5写法的工作由Babel来执行。理由是TypeScript不进行Polyfill。

Polyfill也交给Babel。(如果看不明白可以跳过)

用TypeScript进行编程

src/kintone-typescript-sample.ts:

const HANDLE_EVENT = "app.record.create.show";
interface KintoneEvent {
    record: kintone.types.SavedFiels;
}
kintone.events.on(HANDLE_EVENT, (event: KintoneEvent) => {
    event.record.单价.value = "1";
    event.record.案件负责人.value = [{name: "名字", code: "代码"}];
    return event;
});

webpack进行编译 

npx webpack-cli --mode development

如果输出结果如下,即表示成功。

Starting type checking service...
Using 1 worker with 2048MB memory limit
Hash: 2b19dc578431992634bb
Version: webpack 4.29.3
Time: 2010ms
Built at: 2019-02-14 21:58:08
                       Asset      Size                     Chunks             Chunk Names
kintone-typescript-sample.js  4.15 KiB  kintone-typescript-sample  [emitted]  kintone-typescript-sample
Entrypoint kintone-typescript-sample = kintone-typescript-sample.js

入门教程到处结束。大家辛苦了

IDE补全功能

IDE如果没有做详细的设置,补全功能将无法有效的工作,只会根据以往的输入历史记录进行提示。

但是,有了TypeScript的类型信息,补全功能就会变得特别的强大。

1. 下面是定义了类型信息的情况

typescript-interface.gif

kintone.types.SavedFields是@kintone/dts-gen自定生成的类型信息。

2. 还会补全kintone.events.on等可在kintone上使用的函数

call-function.gif

3. 也会自定补全字段代码,编写代码时将更加得心应手。
0015fab7b468339b807d123939e9c37

4. 如输入的数据类型错了,会显示编译错误,提示你输错了。

0015fab7b35609b27e82c82f31143c8

以上是在VSCode上编写代码的录像,如果发现有类型信息错误,会提示错误。

此Tips在2019年3月版的 kintone中进行确认过。

附件:案件管理(TypeScrip测试用).zip • 3.24KB • 下载