需要安装nodeV14版本以上

安装waft工具

  • 全局安装

    1. npm i waft-cli -g

  • 跟随项目安装

    1. npm i waft-cli --save

  • 如果安装缓慢或失败，建议您切换到淘宝镜像源

    1. npm config set registry https://registry.npm.taobao.org

    waft-cli命令

    | 分类 | 说明 | 命令 | 命令 | | | —- | —- | —- | —- | —- | | 通用 | 查看版本号 | waft -v | ✅ | | | | 查看命令完整的说明 | waft -help | ✅ | | | 初始化 | 创建项目 | waft init | ✅ | | | 开发调试 | 启动内置server + 开启Web调试 | waft start —watch | ✅ | | | 推送预览 | bundle推送预览 | waft push —bundle=build/app.wasm —mock=src/mock.json | ✅ | | | 打包构建 | 构建WASM包 | waft build | ✅ | | | | 构建AOT包 | waft build —aot | ✅ | |

基本使用

创建项目

  1. waft init //即可 询问默认

编译项目

  1. npx waft build //即可 默认会读取 asconfig.json 配置

开发调试

启动调试需要经过以下几个步骤：

  1. 启动调试服务
  2. 终端 链接到调试服务，终端是指：模拟器 或者 真机 器设备。
  3. 打开 chrome 的调试地址查看调试信息，调试信息包括有 log日志，dom渲染（element 和 css 信息）
  4. 推送到终端调试

    这里要注意的是：终端和调试服务必须在同一个局域网环境下才能进行正常工作。

image.png

1. 启动调试服务

在这我们要注意的是这个服务会占用 3 个端口:

  • port : 参数指定的是预览的端口，默认为 8080.
  • chromeDevPort : 这个是 chrome 浏览器 dev 链接的端口，默认为：8020
  • deviceDevPort : 终端链接需要的端口，默认为 8030 并且在 模拟器 和 真机已写死不可更改。

接下来我们在项目路径下运行该命令来启动调试服务。

  1. npx waft start //即可 默认 8080 端口
  2. npx waft start --port=8080 // 指定其他端口

如果服务启动成功，会进入到 repl 模式。我们可以通过 .help 看到到更多的功能。
image.png

2. 终端链接

在上面已经提到过啦，我们终端分为：模拟器 和 真机，连上方式各不相同，其中真机设备需要有前置操作，我们先来看看模拟器。

1. 模拟器链接

用模拟器链接调试比较方便简单，它在启动的时候会自动扫描 8030 端口，如果有挂起，它会自动进行链接，我们可以通过下面命令唤起 模拟器。

  1. # repl 命令
  2. .build                                                             # 编译 app.wasm 文件
  3. .simulator --wasm=build/app.wasm            # 启动模拟器
  5. --wasm 是模拟器启动的时候载入的 .wasm

注意： 目前 simulator 只能支持 .wasm 文件。

模拟器启动会携带的打开 devtools 功能，此时模拟器和 devtools 会同时链接 cli-server 如下图：
image.png
成功启动模拟器如下图：
image.png

注意，如果你是第一次启动模拟，那么后台会有一个下载模拟器的过程，所以在第一次启动模拟器时候，需要耐心等待一下。

模拟器下载中，下载完了就会启动。
image.png

2. 真机设备链接

打开开发者模式 设置—-》更新升级—〉快速连续点击 系统版本号，能打开开发模式。进入开发者模式后， 开启waft调试，SystemUI 上就有快捷触屏入口。
image.png
image.png
waft调试面板快捷入口
image.png
进入调试界面之后，输入 cli 中输入的设备链接服务地址,端口号不用输入。
image.png
image.png
成功链接之后的状态，
image.png

3. 推送调试

我们启动了 cli 服务和终端并且相互建立链接之后，此时我们可以将本地的 bundle 文件推送到终端上运行。注意它们必须在同一局域网环境中，接下来使用 REPL 命令推送即可。

  1. # repl
  2. .push --wasm=build/cards/cards-index-index/cards-index-index.wasm

4. 查看调试信息

通过 devtools 我们可以检查终端的 log 信息以及 dom 信息，在模拟器的情况下 devtools 会随着模拟器一起启动，但是在终端设备模式下，我没需要手动开启。command 按键 + 点击链接即可开启。
image.png
在业务中输出的 log 信息
image.png

cli 命令

waft init

初始化一个项目工程,目前有两个渠道可以获取到脚手架，默认是从 npm 的 cdn 中拉取脚手架，不指定参数如进入询问交互。

  1. npx waft init 
  2. // --project=waft-hello-world     非必填        默认 waft-hello-world

Git

从 Git 的服务上拉取脚手架

  1. npx waft init --git --register=http://gitlab.alibaba-inc.com/aligenie-templates/Genie_Default
  2. // --git             非必填        默认 true
  3. // --register 非必填     默认 http://gitlab.alibaba-inc.com/aligenie-templates/Genie_Default

NPM

从 npm 服务上拉取脚手架

  1. npx waft init --pack=@ali/waft-app-template --ver=0.0.5
  2. // --pack     非必填            默认 @ali/waft-app-template            npm 中 package 的包名称    
  3. // --ver        非必填            默认 tnpm 服务中最新版本                     package 指定的版本号

waft build

编译项目

  1. # 编译单页应用
  2. npx waft build --page=pages/index/index 
  3. // --page          非必填   指定编译的 page        没设置该选项 编译 app.json 引入的全部 page
  5. # 编译卡片应用
  6. npx waft build --card=cards/index/index
  7. // --card         非必填   指定编译的 card

outAssembly

将要编译的 assembly 文件写入到 输出目录中

  1. npx waft build --outAssembly
  2. // --outAssembly     非必填        默认 true                输出 page 编译时的 bind 文件
  4. /* 
  5. 输出文件
  6. build/pages/index
  7.     index.ts                    
  8.     miniapp.ts
  9.     reactor.ts
  10. */

mode

编译模式 dev | prod
dev 模式输出调试文件、log 日志、debug 堆栈、mock 数据
prod 模式 以上信息都不会输出。

  1. npx waft build --mode=dev
  2. // --mode     非必填        默认 dev                如果是 dev 输出调试相关文件 
  4. /* 
  5. 输出文件
  6. build/pages/index
  7.     index.map.js                    
  8.     index.wasm
  9.     index.wat
  10. */
  12. npx waft build --mode=prod 
  13. /* 
  14. 输出文件
  15. build/pages/index        
  16.     index.wasm
  17. */

optimize

优化项

  1. npx waft build --optimizeLevel=2 --shrinkLevel=2
  2. // 'optimizeLevel'   // How much to focus on optimizing code. [0-3]
  3. // 'shrinkLevel'     // How much to focus on shrinking code size. [0-2, s=1, z=2]

aot

在编译的时候，同时输出 .aot 文件

  1. npx waft build --aot=true

本地设备运行

以 adb 的形式将本地编译好的 bundle 推送到设备运行，支持 .wasm 文件和 .aot 文件。

  1. # 指定 wasm 文件地址
  2. waft device --bundle=build/pages/render_006_video/render_006_video.wasm --type=page
  3. // --bundle 指定设备
  4. // --type     指定启动模式  'page' | 'widget' | 'card';

配置文件

默认会读取 asconfig.json 配置文件，但是命令参数会覆盖配置文件的选项

  1. {
  2.   "outAssembly": "true",            //输出 as 的编译文件
  3.   "output": "../build",                //输出编译文件的根目录
  4.   "baseDir": "./src",                    //代码目录
  5.   "mode": "dev"                                //prod 和 dev   dev 会输出 wasm 的 source map 和 js
  6. }

waft 参数

  1. 'git'                   //使用 git 初始化脚手架 
  2.   | 'register'        //git 的项目地址
  3.   // 默认是 tnpm 
  4.   | 'pack'            //包名
  5.   | 'ver'             //版本号 默认最新 
  6.   | 'project'         //初始化的项目名称
  7.   /** waft build */
  8.   | 'baseDir'         // 代码的源目录
  9.   | 'output'          // 输出的根路径
  10.   | 'outAssembly'     // 将要编译的 assembly 文件写入到 输出目录中
  11.   | 'mode'            // 编译模式 dev | prod
  12.   | 'optimizeLevel'   // How much to focus on optimizing code. [0-3]
  13.   | 'shrinkLevel'     // How much to focus on shrinking code size. [0-2, s=1, z=2]
  14.   /** loca-server **/
  15.   | 'port'                        // 启动预览服务的端口

asc 参数

https://www.assemblyscript.org/compiler.html#command-line-options
asc 所有配置文件输出已经被 waft 覆盖了，同时其他参数被继承。

静态预览

在开发阶段为了方便搭建调试 ui 层，快速的反馈 css 和 dom 的视觉结果，所以在该阶段我们是动态分析 ui 层不会应为编译而阻塞打断 ui 外观的调试。

  1. 我么先配置 ui 界面的依赖，这个和小程序一样。我们在 app.json 文件中配置。

    1. # app.json
    2. {
    3. "pages": [                                                                    # 配置需要的页面路径
    4.  "pages/index/index",
    5.  "pages/classes/classes",
    6.  "pages/classes-card/classes-card"
    7. ],
    8. "default": "pages/classes/classes",                    # 配置默认启动页
    9. }

  2. 启动 cli 服务 npx waft start 命令，成功启动之后便会输出静态预览地址。

image.png

设置 viewport

viewport 是适配 rpx 适配屏幕的基准值， rpx 是按照屏幕宽度来计算适配的比率
换算公式： vw = (rpx / viewport).toFixed(2);
如果没设置 viewport 默认是 1024

轻服务卡片示列：

  1. page.json 文件
  2. {
  3.   "usingComponents": {...},
  4.   "viewport": 301,            #可视宽度301
  5.   "viewData":{...}
  6. }

真机设备展示 & web 预览展示
image.pngimage.png

视觉审查

为了高保真的还原设计稿，我们在开发过程中进行像素对比，在 prod 发布模式下不生效。

  1. #page.json
  3. ....
  4. "viewport": 301,
  5. "visualReview": {
  6.   # 对比参照的设计稿
  7.     "url": "https://img.alicdn.com/imgextra/i2/O1CN01x4PxNq1gd9rlaUXDx_!!6000000004164-2-tps-301-220.png",
  8.   # 是否开启
  9.   "enabled": true,
  10.   # 透明度
  11.   "opacity":0.7
  12. },
  13.  ...

浏览器上
image.png
设备上
image.png

升级插件

cli 中集成了一些二方的插件能，目前有：aot 编译器，simulator 模拟器

  1. #升级 aot 编译器
  2. npx waft upgrade aot
  4. #升级 simulator 模拟器
  5. npx waft upgrade simulator