minidev 1.0.3 → 1.0.7

package/docs/guide/commands/dev-daemon-commands/web.md

@@ -0,0 +1,110 @@
+---
+slug: dev-web
+---
+# web
+
+## 用途
+启动开发服务器 Dev Server 之后，运行并打开 Web 版调试器和模拟器。
+
+## CLI 风格使用 
+
+````shell
+# minidev dev 运行之后
+# 界面会显示 
+
+# 可以继续执行以下命令 (可以通过 指令名 -h 来查看参数)
+
+# -  preview : 使用模拟器产物发起真机预览 （此模式仅整包, 无法验证分包可用性）
+# -  remote-debug : 使用模拟器产物发起真机调试 （此模式仅整包）
+# -  ide : 启动小程序开发者工具模拟器进行调试
+# -  web : 启动 Web 模拟器（本地）
+
+# 此时输入 
+
+web
+
+````
+
+可以添加的参数
+
+````
+Options:
+  --auto-open                     [可选] 自动打开模拟器, 默认开启 (default: true)
+  -a, -app-id <appId>             [可选] 小程序应用 id
+  --page <page>                   [可选] 入口页面
+  --page-query <page>             [可选] 页面参数, 可在当前页面的 onLoad 中取得，如: name=vendor&color=black
+  --query <page>                  [可选] 全局参数，app.js 的 onLaunch 中取得，如: name=vendor&color=black
+  --scene <page>                  [可选] 进入场景值
+
+````
+
+## Node.js API 风格使用
+
+````javascript
+
+// 调用前必须先有 devServer
+// const devServerBuild = await minidev.dev({project: 'path/to/project'});
+
+devServerBuild.devServer.once('done', () => {
+  // devServer 构建完成后启动 ide
+  const { bundled, separated } = await minidev.devWebSimulator({
+    appId:'yourAppId',
+    autoOpen:false
+  }, devServerBuild);
+
+  // bundled 中是 web 版本模拟器 & 调试器的地址, 一般来说打开这个地址运行
+  console.log(bundled)
+
+  // separated 中是分离的模拟器和调试器的地址，可以用于更复杂的场景进行集成
+  // 注意：使用时请为每个会话将 url 中的 __uuid__ 替换成模拟器和调试器一致的 uuid。
+  console.log(separated)
+
+});
+
+````
+
+## 参数说明
+
+### autoOpen
+```Typescript
+autoOpen: boolean
+```
+
+是否自动打开模拟器和调试器, 默认开启
+
+### page
+
+### page
+````Typescript
+page: string
+````
+
+
+启动模拟器的的入口页面路径。 例: `/page/index/index`.
+
+
+### pageQuery
+
+````Typescript
+pageQuery: string
+````
+
+
+启动模拟器的的页面参数。可在当前页面的 onLoad 中取得，例: `name=vendor&color=black`
+
+### query
+````Typescript
+query: string
+````
+
+
+启动模拟器的的全局参数。 可在 app.js 的 onLaunch 中取得，例: `name=vendor&color=black`
+
+### scene
+
+````Typescript
+scene: string
+````
+启动模拟器的场景值。 输入值为场景的 channelId。例: `ch_appcenter`
+
+可选值可参考[支持的场景值](../../../guide/experiences/scene.md)。

package/docs/guide/commands/dev.md

@@ -0,0 +1,150 @@
+# dev
+
+## 用途
+
+启动开发服务器 Dev Server
+
+> ###  Dev Server
+> 小程序构建 Dev Server 会对小程序源码目录进行持续的文件监听，当用户对源码进行修改时，及时地生成对应的小程序源码，并启动一个 HTTP 服务允许对产物进行访问。基于此项技术，可以减少代码变更后需要进行完整小程序编译的耗时，提升开发效率。
+
+## CLI 风格使用
+
+````shell
+Usage: minidev dev [options]
+
+启动开发服务器 DevServer
+
+Options:
+  --hmr                               [可选] 是否开启 HMR
+  --host <host>                       [可选] 指定 Host，默认 Host 为 127.0.0.1
+  --port <port>                       [可选] 本地服务的端口号
+  --appxv <appxv>                     [可选] 构建类别，可选值为 v1, v2, legacy-v1 (choices: "v1", "v2", "legacy-v1")
+  --cacheDir <cacheDir>               [可选] 指定构建缓存路径, 默认为系统缓存路径
+  --less                              [可选] 启用 less 编译
+  --typescript                        [可选] 启用 typescript 编译
+  --minify                            [可选] 是否需要压缩，默认不开
+  --ng [ng]                           [可选] (待废弃) 一键设置使用 Appx 2.0，--appxv 优先级更高
+  -o, --output <output>               [可选] 产物路径
+  --parallel [parallel]               [可选] 多进程编译
+  --pluginId <pluginId>               [可选] 插件 Id，构建插件时将生成到代码中
+  --source-map                        [可选] 是否产出 sourceMap (default: true)
+  -p, --project <project>             [可选] 目标项目, 默认为当前工作目录
+  --machine-output                    [可选] 机器可读输出（只显示最终结果）
+  -a, --app-id <appId>                 [可选] > preview 小程序应用 id
+  --auto-push                         [可选] > preview 自动推送到客户端, 默认打开, 使用 --no-auto-push 来关闭 (default: true)
+  --ignore-http-domain-check          [可选] > preview 忽略 http 请求白名单校验
+  --ignore-webview-domain-check       [可选] > preview 忽略 webview 加载域名白名单校验
+  --bundle-id <bundleId>              [可选] > preview <高级> 开放平台 bundleId, 此项会覆盖 clientType 的效果
+  -c, --client-type <clientType>      [可选] > preview 端类型 (choices: "alipay", "ampe", "amap", "genie", "alios", "alipayiot", "uc", "quark", "health", "koubei", "taobao", "cainiao", "alihealth", "OTT_CIBN",
+                                      "OTT_TAITAN")
+  --page <page>                       [可选] > preview 入口页面
+  --page-query <page>                 [可选] > preview 页面参数, 可在当前页面的 onLoad 中取得，如: name=vendor&color=black
+  --query <page>                      [可选] > preview 全局参数，app.js 的 onLaunch 中取得，如: name=vendor&color=black
+  --scene <page>                      [可选] > preview 进入场景值
+  --simulate-update                   [可选] > preview 模拟更新
+  --ampe-device-id <ampeDeviceId>     [可选] > preview [AMPE] 设备 ID
+  --ampe-host-app-id <ampeHostAppId>  [可选] > preview [AMPE] 产品 ID
+  --ampe-product-id <ampeProductId>   [可选] > preview [AMPE] 移动应用 ID
+  --app-path                          [可选] > ide IDE 安装路径 
+   示例：MacOS:  /Applications/小程序开发者工具.app 
+   Windows: C:\Program Files\小程序开发者工具 
+  --lite                              [可选] > ide 使用 Lite 模式启动 IDE
+  --project-type                      [可选] > ide 项目类型
+  --auto-open                         [可选] > web 自动打开模拟器, 默认开启 (default: true)
+````
+
+## Node.js API 风格使用
+
+````javascript
+
+  // 启动一个 devServer
+  const { devServer } = await minidev.dev({
+    project: '/path/to/project'
+  });
+  // 注意此时 devServer 还未编译完成
+  
+  // 添加编译完成的监听
+  devServer.on('done', () => {
+    console.log('编译完成');
+    console.log(devServer.server);
+  });
+  
+  devServer.on('error', (error) => {
+    console.log('编译失败, 错误信息:', error.message);
+  });
+  
+  devServer.on('exit', (code) => {
+    console.log('DevServer 进程退出, 退出code', code);
+  });
+  
+  devServer.on('log', (data) => {
+    console.log('[devServer日志]', data);
+  });
+
+````
+
+## 后续指令
+
+devServer 服务器启动并**编译完成后**，可以基于 devServer 的构建产物继续执行后续指令， 目前支持的指令有:
+
+- [ide](../../guide/commands/dev-daemon-commands/ide.md) 启动 IDE Lite 模式进行模拟器调试
+- [web](../../guide/commands/dev-daemon-commands/web.md) 启动 web 版本模拟器进行调试
+- [preview](../../guide/commands/dev-daemon-commands/preview.md) 使用模拟器的产物进行真机预览（快速真机预览）
+- [remote-debug](../../guide/commands/dev-daemon-commands/remote-debug.md) 使用模拟器的产物进行真机调试（快速真机调试）
+
+
+> ### Tip: 提前输入参数
+> minidev dev -h 中展示的参数以 > xxxx 开头的为后续指令消费的参数，为了方便可以在 dev 指令启动时提前输入，这样就无需在每次进行后续指令时键入。
+> 
+> ``
+> --ignore-webview-domain-check       [可选] > preview 忽略 webview 加载域名白名单校验
+> ``
+> 
+> 如上面这个就是后续真机预览 preview 指令会消费的参数，我们可以在启动 dev 指令时输入 
+> 
+> ``
+> minidev dev --ignore-webview-domain-check
+> ``
+> 
+> 这样后续输入的所有 preview 指令都会忽略 webview 的白名单校验
+
+
+
+## 参数说明
+
+### hmr 
+
+是否开启代码热更新（默认关闭）
+
+> 在使用 IDE 模拟器或者web版本模拟器时，如果代码热更新启用，修改 axml，acss 和某些 js 代码时，如果条件允许，将不会完全刷新当前页面，而仅仅进行局部的小粒度更新，在快速调整样式和简单逻辑时较为方便。
+
+### host
+
+Dev Server 提供的 HTTP 服务的 host 地址，默认为 127.0.0.1
+
+### port 
+
+Dev Server 提供的 HTTP 服务的端口号，默认为随机可用端口
+
+### appxv
+
+同 [build指令](../../guide/commands/build.md) 中同名参数
+
+### cacheDir
+
+同 [build指令](../../guide/commands/build.md) 中同名参数
+
+### minify
+
+同 [build指令](../../guide/commands/build.md) 中同名参数
+
+### ng
+
+同 [build指令](../../guide/commands/build.md) 中同名参数
+
+### output
+
+同 [build指令](../../guide/commands/build.md) 中同名参数
+
+### sourceMap
+同 [build指令](../../guide/commands/build.md) 中同名参数

package/docs/guide/commands/download-assets.md

@@ -0,0 +1,48 @@
+# download-assets
+
+## 用途
+
+下载支付宝小程序 CLI 将会用到的资源文件。
+
+除非添加了 `--clean-previous`参数，重复执行这个指令不会重复下载已下载过的资源文件。
+
+> 支付宝小程序 CLI (minidev) 在 postinstall 过程中会默认执行 download-assets 指令下载所需的离线资源包。
+> 
+> 下载的资源包默认保存在用户目录下的 `.minidev/assets` 文件夹内。
+> 
+> 如果需要将 minidev 在离线环境或者网络隔离环境内使用，可以在网络通畅时手动执行 
+> `minidev download-assets --with-compiler`
+> 来保证离线使用时不会再尝试请求资源。
+
+## CLI 风格使用 
+
+````
+Usage: minidev download-assets [options]
+
+下载离线资源包
+
+Options:
+  --clean-previous  [可选] 清除已有下载的离线资源，重新下载
+  --with-compiler   [可选] 同时下载构建器
+````
+
+## Node.js API 风格使用
+
+```` javascript
+
+minidev.downloadAllAssets({
+  withCompiler: true
+})
+
+````
+
+## 参数说明
+
+### cleanPrevious
+
+清除已有下载的离线资源，重新下载
+
+### withCompiler
+
+由于构建器资源较大和版本变化，默认在安装 （postinstall) 时不会尝试下载构建器，仅仅会在启用需要构建器的命令（如 dev, build 等) 时才会尝试下载构建。添加这个参数来在下载离线资源的同时下载构建器。
+

package/docs/guide/commands/ide.md

@@ -0,0 +1,117 @@
+---
+slug: ide
+---
+# ide
+
+## 用途
+
+启动小程序开发者工具（要求小程序开发者工具版本 >= 2.3)
+
+
+## CLI 风格使用 
+
+````shell
+Usage: minidev ide [options]
+
+启动IDE
+
+Options:
+  --app-path               [可选] IDE 安装路径 
+   示例：MacOS:  /Applications/小程序开发者工具.app 
+   Windows: C:\Program Files\小程序开发者工具 
+  --lite                   [可选] 使用 Lite 模式启动 IDE
+  --project-type           [可选] 项目类型
+  -p, --project <project>  [可选] 目标项目, 默认为当前工作目录
+  --machine-output         [可选] 机器可读输出（只显示最终结果）
+  -h, --help               display help for command
+````
+
+## Node.js API 风格使用
+
+````javascript
+  minidev.startIde({
+    project: '/path/to/project',
+    lite: true,
+  }); 
+````
+
+## 参数说明
+
+### appPath
+
+````Typescript
+appPath: string
+````
+
+支付宝小程序开发者工具的安装路径, MacOS 和 Windows 指向默认地址示例：
+
+- `MacOS`:  /Applications/小程序开发者工具.app 
+- `Windows`: C:\Program Files\小程序开发者工具
+
+如果不传入此参数，会使用上述的默认地址尝试查找小程序开发者工具，如果没办法找到可用的 IDE，会抛出错误。
+
+### projectType
+
+````Typescript
+projectType: string 
+````
+
+对应打开的小程序项目类型, 如果不传入，默认使用支付宝小程序类型打开
+
+常用小程序项目类型列表可选值:
+
+- `alipay-mini` 支付宝小程序
+- `alipay-mini-plugin` 支付宝小程序插件
+- `dingtalk-biz` 钉钉企业内部应用
+- `dingtalk-biz-custom` 钉钉企业定制应用
+- `dingtalk-biz-isv` 钉钉第三方企业应用
+- `dingtalk-biz-worktab-plugin` 钉钉工作台组件
+- `dingtalk-personal` 钉钉第三方个人应用
+- `alios-project` 阿里车小程序
+- `com.alipay.koubeimerchant` 口碑掌柜小程序
+- `com.cainiao.app` 橙运小程序
+- `com.cainiao.cs.app` 包裹侠小程序
+- `com.cainiao.edgeboxapp` 小Yi工作台小程序
+- `com.cainiao.station.app` 驿站掌柜小程序
+- `com.cainiao.station.dfs` 海南自提点小程序
+- `com.cainiao.station.hk` 香港自提点小程序
+- `com.cainiao.station.sto` 喵站喵站
+- `com.cainiao.wireless` 菜鸟裹裹小程序
+- `com.dwd.rider.app` 点我达小程序
+- `com.taobao.movie.tinyside` 淘票票小程序
+- `com.uc.app.localDebugProjectType` UC小程序
+- `ALIDATA-mini` 阿里数据小程序
+- `ALIDATA-mini-appx-2.0` 阿里数据AppX 2.0小程序
+- `alihealth-mini-plugin` 阿里医院小程序插件
+- `com.youku.app` 优酷小程序
+- `exclusive-dingtalk-card` 专有钉钉工作台组件
+- `exclusive-dingtalk-personal` 专有钉钉标准小程序
+- `exclusive-dingtalk-personal-mpaas` 专有钉钉mPaaS小程序
+- `gaode-mini` 高德小程序
+- `gaode-mini-plugin` 高德小程序插件
+- `hk-mini` 香港版支付宝小程序
+- `kcatering-miniapp` 客如云KPOS餐饮小程序
+- `kcatering-miniapp-plugin` 客如云KPOS餐饮小程序插件
+- `klauncher-miniapp` 客如云POS桌面小程序
+- `klauncher-miniapp-plugin` 客如云POS桌面小程序插件
+- `kmobile-miniapp` 掌上客如云小程序
+- `kmobile-miniapp-plugin` 掌上客如云小程序插件
+- `koubei-mini` 口碑小程序
+- `koubei-mini-plugin` 口碑小程序插件
+- `mPaaS` mPaaS小程序
+- `quark-mini-plugin` Quark小程序插件
+- `tgcc-project` 天猫精灵小程序
+- `tmall-genie-app-standard-miniapp` 天猫精灵APP小程序
+- `tmall-genie-app-standard-miniapp-plugin` 天猫精灵APP小程序插件
+- `uc-mini-plugin` UC小程序插件
+- `xiniaoMiniProgram` 溪鸟溪鸟
+- `xpaas-mini` 支付宝 IoT小程序
+- `xpaas-mini-plugin` 支付宝 IoT小程序插件
+- `youku-mini-plugin` 优酷小程序插件"
+
+### lite
+````Typescript
+lite: boolean
+````
+
+是否使用 [Lite 模式](https://opendocs.alipay.com/mini/ide/idelite) 启动 IDE，此场景下默认为 false

package/docs/guide/commands/index.md

@@ -0,0 +1,19 @@
+---
+slug: command-index
+title: 指令列表
+---
+
+## 小程序开发
+
+* [build](./build.md)
+* [dev](./dev.md)
+* [preview](./preview.md)
+* [remote-debug](./remote-debug.md)
+* [upload](./upload.md)
+* [ide](./ide.md)
+
+## CLI 工具管理
+
+* [login](./login.md)
+* [download-assets](./download-assets.md)
+* [config](./config.md)

package/docs/guide/commands/login.md

@@ -0,0 +1,53 @@
+---
+slug: command-login
+title: login
+---
+
+## 用途
+
+对工具进行快捷授权
+
+## CLI 调用方法
+
+````shell
+Usage: minidev login [options]
+
+进行工具授权
+````
+
+## Node.js API 调用方法
+
+
+````javascript 
+
+// minidev.login() 返回的 promise resolve 代表登录完成，如过登录失败，会 reject
+await minidev.login({
+  project: 'path/to/mini-program'
+}, (loginTask) => {
+  // Node.js API 方式可以通过第二个参数获取 loginTask 以便后续展示等
+  loginTask.on('qrcode-generated', (qrcodeUrl) => {
+    // 已获取登录图片，进行后续展示
+    console.log(qrcodeUrl);
+  });
+
+  loginTask.on('polling', (remainingMs) => {
+    console.log(`二维码过期时间: ${Math.floor(remainingMs / 1000)}s`);
+  })
+
+  loginTask.on('success', (remainingMs) => {
+    console.log(`完成授权`);
+  })
+
+  loginTask.on('scan', (remainingMs) => {
+    console.log(`已扫描, 请在手机上确认`);
+  })
+
+})
+````
+
+## 注意事项
+
+参见 [授权信息使用注意事项](../../guide/experiences/auth.md)
+
+
+

package/docs/guide/commands/preview.md

@@ -0,0 +1,121 @@
+# preview
+
+## 用途
+
+构建小程序并发起真机预览。 
+
+运行后，支付宝小程序 CLI 将会构建可以在手机 App （如支付宝钱包）中使用的预览版小程序，并将其发布到支付宝开放平台供手机 App 访问。
+
+![](https://intranetproxy.alipay.com/skylark/lark/0/2021/png/111910/1638457569239-7fb20881-2083-4f21-940a-8135acf69e13.png?x-oss-process=image%2Fresize%2Cw_1284%2Climit_0)
+
+运行成功后，将会返回可供手机 App 扫描的小程序预览二维码，使用对应手机 App 扫码即可查看小程序。部分 App 支持自动同步小程序到手机 App 中，无需进行扫码操作。
+
+> 使用该指令要求工具进行[授权](../../guide/experiences/auth.md)
+## CLI 风格使用 
+
+````
+Usage: minidev preview [options]
+
+发起真机预览
+
+Options:
+  --auto-push                         [可选] 自动推送到客户端, 默认打开, 使用 --no-auto-push 来关 (default: true)
+  --ignore-http-domain-check          [可选] 忽略 http 请求白名单校验
+  --ignore-webview-domain-check       [可选] 忽略 webview 加载域名白名单校验
+  -a, --app-id <appId>                [必填] 小程序应用 id
+  -c, --client-type <clientType>      [可选] 端类型 
+  --page <page>                       [可选] 入口页面
+  --page-query <page>                 [可选] 页面参数, 可在当前页面的 onLoad 中取得，如: name=vendor&color=black
+  --query <page>                      [可选] 全局参数，app.js 的 onLaunch 中取得，如: name=vendor&color=black
+  --scene <page>                      [可选] 进入场景值
+````
+
+## Node.js API 风格使用
+
+````javascript
+
+const { qrcodeSchema, qrcodeUrl, version } = await minidev.preview({
+  appId: 'YourAppId',
+  project: '/path/to/mini-program',
+})
+
+// 预览二维码图片地址
+console.log(qrcodeUrl);
+
+// 预览 schema url，允许手机 App 通过这个 url 唤起预览小程序
+console.log(qrcodeSchema);
+
+// 生成的临时版本号，对于插件项目可以用于宿主进行插件联调
+console.log(version);
+
+````
+
+
+## 参数说明
+
+### appId
+````Typescript
+appId: string
+````
+本次真机预览使用的小程序 App Id。
+
+### clientType
+````Typescript
+clientType: string
+````
+
+指定真机预览的目标端类型，默认为 alipay (支付宝)，详见[端类型](../../guide/experiences/client-type.md)。
+
+### autoPush
+````Typescript
+autoPush: boolean
+````
+
+如果指定的端（手机 App) 支持，则尝试将预览的小程序直接推送到端，无需进行扫码操作。 此功能默认开启。
+
+### ignoreHttpDomainCheck
+````Typescript
+ignoreHttpDomainCheck: boolean
+````
+
+此次真机预览的小程序运行时忽略 http 请求白名单校验。详见 [小程序网络 API 使用须知](https://opendocs.alipay.com/mini/008gq6)
+
+
+### ignoreWebviewDomainCheck
+````Typescript
+ignoreWebviewDomainCheck: boolean
+````
+
+此次真机预览的小程序运行时忽略 web-view 组件加载域名白名单校验。详见[ web-view 组件 H5 域名配置](https://opendocs.alipay.com/mini/component/idfvg6)
+
+### page
+````Typescript
+page: string
+````
+
+本次预览的入口页面路径。 例: `/page/index/index`.
+
+
+### pageQuery
+
+````Typescript
+pageQuery: string
+````
+
+本次预览的页面参数。可在当前页面的 onLoad 中取得，例: `name=vendor&color=black`
+
+### query
+````Typescript
+query: string
+````
+
+本次预览的全局参数。 可在 app.js 的 onLaunch 中取得，例: `name=vendor&color=black`
+
+### scene
+
+````Typescript
+scene: string
+````
+本次预览的场景值。 输入值为场景的 channelId。例: `ch_appcenter`
+
+可选值可参考[支持的场景值](../../guide/experiences/scene.md)。