使用TypeScript开发kintone自定义 - cybozu

概要

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

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

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

什么是TypeScript

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

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

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

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

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

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

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

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

参考: TypeScript in 5 minutes ,TypeScript Playground, TypeScript 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

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