simple-qatool

1.0.5 • Public • Published

快应用打包管理工具

基于快应用hap工具再简单封装的一个打包工具。用于应对版本提升,简单的不同环境的模板代码替换。

安装

普通安装 npm install simple-qatool

也支持全局安装 npm install -g simple-qatool

工具本身依赖了hap打包工具,如果是全局使用,请先确认你已安装完工具并在项目目录执行过初始的npm install。参考快应用hap工具

使用

因为替换模板需要,初次使用需要初始化,执行 qatool init

初始化会询问一些相关配置的内容,其中问题后面的括号内的内容表示默认值。

因为快应用有“版本名称”和“版本号”两个版本标识的概念,和一般理解不同,“版本号”不是形如1.0.0这样的,而是纯数字,每次发版至少加1。而“版本名称”才是用来放1.0.0这样的数字的地方。

工具初始化时会询问期望的版本名称,其中可以用占位符。占位符支持如下:

占位符 替换内容
{name} 应用英文名称(init时填写)
{version} 应用版本代号,即形如1.0.0这样的版本号
{versionCode} 应用版本号,即快应用配置的versionCode
{mode} 打包模式
{timeStamp} 打包时间,采用YYYYMMDDHHmm的形式

初始化后,会在当前项目目录下新建一个 ads_qatool 的文件夹,目录结构如下:

ads_qatool
├─config
├─template
└─appConfig.json

其中 config 用于存放不同环境下的配置文件,三个文件分别对应三个指令执行时的环境,即dev.env.js对应执行qatool dev 时的环境变量配置。

template 则用于存放模板文件需要替换的模板文件, 其中必须包含manifest.json。初始化时工具会将项目中的manifest.json 复制到 template 下并根据初始化指令更新其中的数据。日后需要修改配置文件时,请修改此目录下的这个文件。

如果不是全局安装不能执行qatool init时,请手动创建此文件夹和对应的目录以及文件,或者使用对应的相对目录来执行命令。

模板替换

工具提供了模板替换的功能,用于根据不同的环境替换不同的值,这是做这个工具的初衷之一。(其实快应用的webpack工具有使用definePlugin来暴露全局变量,但似乎他们文档中并未提到这个事情,担心后续会更改,所以没有使用。)

所以放在/ads_qatool/template/目录下的文件以及子文件夹,都对应会替换到/src/的对应文件上,如果没有对应文件则输出一份到/src/。即/ads_qatool/template/app.ux 在执行后会输出到 /src/app.ux

替换的模板格式很简单,在模板文件中使用<%=key%>表示需要替换的内容,在/ads_qatool/config/目录下的文件中,使用对应的key来定义改环境下需要替换的变量。三个文件分别对应三个指令下的配置。

当然如果需要使用模板替换的功能,则日后修改任何模板文件,都应该修改template目录下的文件,而不是src目录下的,否则执行指令时,会被工具用模板文件替换掉。这一点请务必注意。
推荐模板文件都是一些公共的配置文件,尽量不要在业务代码内使用模板,这样可以减少调试时去修改模板文件的情况,从而减少忘记修改的情况。

请记住这里是简单的文本替换,如果你需要是字符串需要自己在模板内加""。但如果替换内容确定是数字,那就什么都不用加:

// 如果name是字符串
let name = <%=name%>; // × 这样做一般都会报错
let name = "<%=name%>"; // √

// 数字则不要加""了。
let count = <%=count%>;

也因为是简单的文本替换,如果内容内存在引号冲突,需要再转义一次。

// dev.env.js
module.exports = {
    quoted: "这是一个\\\"有引号\\\"的字符串!" // 注意是三个 \
};
 
// 模板代码内
let quoted = "<%=quoted%>";
 
// 当然,这里还是可以用单双引号的方式来规避,比如:
// dev.env.js
module.exports = {
    quoted: '这是一个"有引号"的字符串!' // 这里不需要转义了
};
 
// 模板代码内
let quoted = '<%=quoted%>';
 

你也可以不将任何其他文件放到/ads_qatool/template/目录下(manifest.json是必要文件),这样也可以体验本工具提供的版本控制的功能。关于版本控制部分,注意查看参数部分的 -b-e-f 指令。

为啥不直接把模板放到src下并替换呢?
最初考虑也是这么干,后面想了下,这工具毕竟是依附在hap工具上的,如果直接在src里面放模板文件,那hap的自带的所有指令打包出来的文件都是模板原文件,里面的<%=key%>不会被替换。而单独起一个目录虽然会带来文件修改的麻烦,但这样在项目目录下再执行hap的指令都不会受到影响。

指令

  • qatool init 初始化工具配置,会新建工具文件夹和初始化manifest.json。
  • qatool dev [options] 执行dev环境模板替换,根据参数可以打包或者启动本地服务器。
  • qatool beta [options] 执行beta环境模板替换,根据参数可以打包或者启动本地服务器。
  • qatool publish [options] 执行publish环境模板替换,根据参数可以打包或者启动本地服务器。

参数

指令中对应的options参数支持如下:

  • -b, --bump 版本名称升级一个小版本,如当前版本为 1.0.0,使用此参数打包结果中的版本会升级至 1.0.1。注意“版本号”每次打包都会更新,不论是否加此参数。同时此参数只会更新版本,并不会将结果写入配置文件,需要需要更新配置文件,请和-f一起使用。
  • -e version, --explicit version 指定版本名。-b参数用于升级末位的小版本,但当需要设置特定版本时,可以使用此参数。-e 1.1.0 会将打包结果中的版本名设置为1.1.0。注意“版本号”每次打包都会更新,不论是否加此参数。同时此参数只会设置版本,并不会将结果写入配置文件,需要需要更新配置文件,请和-f一起使用。
  • -f, --permanent 将版本号和版本名的更新写入文件。默认情况下,-b-e参数对版本名的操作不会更新到文件中,以防止出现过多的版本名和版本号的提升。
  • -l logLevel, --log logLevel 指定日志等级,logLevel参数必须是off|debug|log|info|warn|error中的一个。
  • -p port, --port port 本地服务器端口,默认 12306。必须同时包含-s参数才会生效。
  • -s, --server 启动本地服务器。
  • -u, --debug-sign 使用debug签名来发布rpk,正常情况下请勿添加此参数
  • -w, --watch 启动文件监听。必须同时包含-s参数才会生效。
  • --help 查看帮助内容

上面不需要额外输入值的参数,可以通过在面前加上--no来关闭,注意是 --no,两个 -

-w, --watch 使用的是快应用工具本身的watch,所以在watch模式下更改任何ads_qatool下的模板文件或者配置文件,都不会生效,需要重新执行命令。 默认情况下,工具指令并不包含上述任何参数,所以dev、beta、publish都是替换环境配置内容并打包。如果不是全局安装的qatool,推荐使用npm scripts来添加执行指令,比如在npm scripts将 npm run dev 设置为执行 qatool dev -sw -l debug

Readme

Keywords

Package Sidebar

Install

npm i simple-qatool

Weekly Downloads

1

Version

1.0.5

License

ISC

Unpacked Size

33.3 kB

Total Files

8

Last publish

Collaborators

  • carrotb