快应用学习

快应用的架构和使用以及和vue的区别、搭建快应用开发环境。

一、技术栈

1.1 快应用整体架构

分为三层：

应用层
   ↓
框架层
   ↓
系统能力层

应用层（Application Layer）,开发者编写的代码，包括了：

• UX页面
• JS逻辑
• CSS样式
• 组件

主要结构：

src
 ├─ pages
 ├─ components
 ├─ common
 └─ app.ux

开发者只需要写：UI,逻辑,业务代码,类似：Vue组件

框架层（Framework Layer），快应用框架负责：

• 页面渲染

• 组件系统

• 路由管理

• 生命周期

• 数据绑定

类似：Vue Runtime

框架会提供：

系统能力层（System Service），直接调用手机系统能力，例如：

• 相机

• 位置

• 文件

• 网络

• 蓝牙

例如调用：

import prompt from '@system.prompt'

prompt.showToast({
  message: 'hello'
})

这是 系统级 API。

1.2 快应用技术架构

快应用核心技术：

UX语言 + JS + CSS

一个页面文件，比如 index.ux

结构：

<template>
</template>

<script>
</script>

<style>
</style>

类似：

Vue SFC（单文件组件）

1.3 快应用与 Vue 的联系

其实 快应用设计思路很像 Vue。

例如：

<template>
  <div></div>
</template>

<script>
export default {
  data(){
    return { msg:'hello'}
  }
}
</script>

快应用

<template>
  <text></text>
</template>

<script>
export default {
  data:{
    msg:'hello'
  }
}
</script>

可以看到，几乎一样。

1.4 快应用 vs Vue 的区别

虽然很像，但底层完全不同。

UI组件不同

Vue：

div
span
img

快应用：

div
text
image
list

例如：

<text>Hello</text>

API不同

Vue：

window
document
fetch

快应用：

@system.*

例如：

@system.file
@system.storage
@system.prompt

生命周期不同

Vue：

• created
• mounted
• updated

快应用：

• onInit
• onShow
• onReady
• onDestroy

路由不同

Vue：

vue-router

快应用：

router.push()

示例：

router.push({
 uri:'pages/detail'
})

1.5 快应用开发流程

开发流程基本是：

创建项目
 ↓
写页面
 ↓
调试
 ↓
打包
 ↓
发布

1 初始化项目

hap init project

2 启动调试

npm run server

3 真机调试，手机安装快应用调试器

4 打包，生成xxx.rpk,类似安卓的APK

1.6 快应用能否使用第三方依赖

支持，但有条件。因为快应用项目本身就是 Node + npm 项目，所以可以安装依赖：

npm install axios

然后在代码中使用：

import axios from 'axios'

但必须满足一个前提：依赖不能依赖浏览器 DOM 或 Node 环境。

因为快应用运行环境既不是：

• 浏览器

• Node.js

而是 手机系统 Runtime。

1.6.1 哪些 JS 库可以使用

纯 JS 工具库（基本都能用）

例如：

示例：

npm install dayjs
import dayjs from 'dayjs'

let time = dayjs().format('YYYY-MM-DD')

这种库 完全没问题。

数据处理类库

例如：

• mathjs
• qs
• validator

因为它们只是 纯JS逻辑。

1.6.2 哪些 JS 库不能使用

DOM相关库

例如：

• jquery
• zepto

原因：

快应用没有：

• document
• window
• DOM

所以这类库会报错。

浏览器 API 库

例如，依赖：

• localStorage
• window
• fetch

快应用需要使用：

• @system.storage
• @system.fetch

Node.js 库

例如：

• fs
• path
• express

因为快应用不是 Node 环境。

1.6.3 UI 库能不能使用

Vue UI库基本不能用。

例如：

原因： 这些库依赖 HTML DOM。而快应用 UI 组件是：

• text
• image
• div
• list
• input

这些都不是 HTML。

1.6.4 快应用自己的 UI 组件

快应用自带组件：

例如：

<list>
  <list-item>
    <text>Hello</text>
  </list-item>
</list>

1.6.5 第三方快应用 UI 库

虽然不多，但有一些：

• Vant QuickApp，类似 Vant for Vue，但生态比较小。

• 官方组件扩展，厂商提供，比如华为组件、系统组件、oppo、vivo等

推荐依赖类型

开发快应用推荐使用：

工具类：

• lodash
• dayjs
• uuid 请求类：
• axios 数据处理：
• qs
• crypto-js

一个真实快应用项目可能有：

{
  "dependencies": {
    "axios": "^1.6.0",
    "dayjs": "^1.11.0",
    "lodash": "^4.17.21",
    "qs": "^6.11.0",
    "crypto-js": "^4.2.0"
  }
}

快应用依赖打包原理

快应用编译流程：

UX文件
 ↓
JS编译
 ↓
打包RPK
 ↓
运行在手机Runtime

npm依赖会：

node_modules
 ↓
webpack打包
 ↓
一起打进RPK

所以：

只要是纯JS就能打包。开发快应用可以这样理解：

快应用 = Vue语法 + 原生组件 + 纯JS库

能用：

• JS工具库
• 数据处理库
• 请求库

不能用：

• Vue UI库
• DOM库
• Node库

二、安装开发环境

我是 Linux/Ubuntu 操作系统，所以我下载安装的是 Linux 版本的 IDE，其实这个没有关系，也支持 Windows 和 Mac 的，这个 IDE 本质上就是 VSCode定制而来。而使用 VSCode + Node + hap-toolkit 也能够搭建开发环境，而且还能享用 VSCode的各种好用的插件

2.1 使用原生 quickapp-IDE

下载地址的页面：

https://www.quickapp.cn/devtool/quickapp

Linux版本的下载地址：

https://statres.quickapp.cn/quickapp/show/ide/quickapp-ide-3.3.1.deb

安装命令：

wget https://statres.quickapp.cn/quickapp/show/ide/quickapp-ide-3.3.1.deb

sudo apt install ./quickapp-ide-3.3.1.deb

注意，这里有坑(这也是为什么最好使用 VSCode 来搭建快应用开发环境，而不是使用官网提供的 IDE,官网提供的最新的安装包 QuickApp IDE 3.3.1 是 2019-2020 的 Electron 版本，在 Ubuntu 22/24 经常有兼容问题，而且功能非常落后，自己给VSCode安装插件和依赖也能搭建完整的开发环境)

这样安装会报错，提示：

agile@agile-book-linux:~/Downloads$ sudo apt install ./quickapp-ide-3.3.1.deb 
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'quickappide:i386' instead of './quickapp-ide-3.3.1.deb'
The following NEW packages will be installed:
  quickappide:i386
0 upgraded, 1 newly installed, 0 to remove and 93 not upgraded.
Need to get 0 B/137 MB of archives.
After this operation, 4,194 kB of additional disk space will be used.
Get:1 /home/agile/Downloads/quickapp-ide-3.3.1.deb quickappide i386 3.3.1 [137 MB]
dpkg: error processing archive /home/agile/Downloads/quickapp-ide-3.3.1.deb (--unpack):
 package architecture (i386) does not match system (amd64)
Errors were encountered while processing:
 /home/agile/Downloads/quickapp-ide-3.3.1.deb
N: Download is performed unsandboxed as root as file '/home/agile/Downloads/quickapp-ide-3.3.1.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
E: Sub-process /usr/bin/dpkg returned an error code (1)

报错核心是这一句：package architecture (i386) does not match system (amd64)，意思是系统架构为amd64（64位），但是安装包架构却是i386（32位），而且系统没有启用 32 位架构支持，所以 dpkg 拒绝安装。

解决：

sudo dpkg --add-architecture i386
sudo apt update
sudo apt install ./quickapp-ide-3.3.1.deb

如何查看安装包的架构

dpkg-deb -I quickapp-ide-3.3.1.deb | grep Architecture
#打印输出 Architecture: i386 说明是32位，amd64则是64位

安装好 IDE 之后，应用导航栏会出现 “快应用开发工具”的图标，直接打开即可，但是这里也有坑，就是点击之后没有任何反应，这大概又是依赖或者权限的问题，导致无法运行应用程序，但是由于是可视化运行，所以没有提示信息，那么直接去控制台打开，然后看报错

cd /opt/quickAppIDE
./quick-app-ide

然后报错如下：

[22186:0311/225025.442627:FATAL:setuid_sandbox_host.cc(157)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /opt/quickAppIDE/chrome-sandbox is owned by root and has mode 4755. Trace/breakpoint trap (core dumped)

这是 Electron 程序的 sandbox 权限问题，很多旧 IDE 在 Ubuntu 上都会遇到。执行如下命令即可修复：

sudo chown root:root /opt/quickAppIDE/chrome-sandbox
sudo chmod 4755 /opt/quickAppIDE/chrome-sandbox

然后就可以提供图标直接打开，当然命令行也可以了。

然后会弹出创建应用的快捷导航(可以创建空应用，也可以创建一个模板应用)：

然后会需要填写应用信息：

在创建快应用（Quick App）项目时，这四个参数决定了项目的工程结构、应用标识和显示信息。以下是它们的具体含义：

1. projectName（项目名称） 定义：本地开发时的工程文件夹名称。 用途：仅用于在电脑上标识该代码仓库。例如，执行 hap init demo 时，demo 就是 projectName，它会创建一个名为 demo 的文件夹。 规范：建议使用英文小写和中划线（如 my-quickapp-project）。

2. projectPath（项目路径） 定义：项目在硬盘上的物理存放位置。 用途：告诉开发工具（如 IDE）或命令行工具将代码下载/初始化到哪个具体的目录。

3. appName（应用名称） 定义：用户在手机上看到的实际图标名称。 用途：配置在 manifest.json 中的 name 字段。当用户在桌面、搜索结果或管理列表中看到你的快应用时，显示的文字就是这个值。 规范：通常为中文，应简洁且具有辨识度（如“极速浏览器”）。

4. package（包名） 定义：应用的唯一身份标识符。 用途：这是快应用在全网及各手机厂商平台中的唯一 ID。如果你更新应用，包名必须保持一致；如果包名变了，系统会认为这是一个全新的应用。 规范：通常采用反向域名格式。 例如：com.company.project 注意：一旦发布，包名不可更改，否则会导致无法覆盖安装或丢失现有用户。

参数对比速查表

填写完毕之后，应用的基本工程目录就形成了。

初始化后一般类似这样：

quickapp-demo/
│
├── node_modules/        # npm依赖
├── src/                 # 主要开发代码
│
├── sign/                # 应用签名文件
├── dist/                # 打包后的快应用
│
├── package.json         # npm配置
├── manifest.json        # 应用配置
├── babel.config.js      # babel配置
├── postcss.config.js    # css处理
└── README.md

核心目录说明：

1. src（最重要） 所有页面和逻辑代码都在这里。

src/
│
├── app.ux
├── pages/
├── common/
├── components/
└── i18n/

app.ux：应用入口文件，相当于：Vue 的 App.vue或者小程序的 app.js，主要作用：全局生命周期，全局样式，全局状态

示例：

<style>
.page {
  background-color: #f5f5f5;
}
</style>

<script>
export default {
  onCreate() {
    console.log('app create')
  }
}
</script>

pages（页面）:每个页面一个 .ux 文件。

pages/
   index/
      index.ux
   about/
      about.ux

相当于：Vue 页面或者小程序 page

示例：

<template>
  <div class="container">
    <text>Hello QuickApp</text>
  </div>
</template>

<script>
export default {
  data: {
    message: 'hello'
  }
}
</script>

common（公共代码）:存放包括工具函数，api封装，常量，例如：

common/
   api.js
   utils.js
   config.js

components（组件）：可复用组件。

components/
   header/
      header.ux
   card/
      card.ux

类似：Vue组件或者React组件

i18n（国际化）是可选目录，用于：多语言支持

i18n/
   zh-CN.json
   en-US.json

manifest.json（非常重要），这是 快应用核心配置文件。类似 安卓开发中的AndroidManifest或者小程序中的app.json

示例：

{
  "package": "com.demo.quickapp",
  "name": "quickapp-demo",
  "versionName": "1.0.0",
  "versionCode": 1,
  "icon": "/assets/icon.png",
  "router": {
    "entry": "pages/index",
    "pages": {
      "pages/index": {
        "component": "index"
      }
    }
  }
}

关键字段：

sign（签名目录）

sign/
   debug.pem
   private.pem

用于：快应用签名和打包安装，类似 Android APK 签名。

dist（打包输出），会在这个目录下生成文件：appname.rpk，这是快应用安装包，类似 APK 文件

dist/
   quickapp-demo.rpk

开发常用命令

# 1 初始化
hap init project

# 2 安装依赖
npm install

# 3 启动调试
npm run server
#或
hap server

# 4 打包
npm run build
#生成：dist/*.rpk

如果执行了 npm install 之后，右侧预览窗口还是没有出现预览效果，

那么，如何在自己的手机上进行测试呢？

可以通过在手机上安装快应用调试器这一应用，然后通过这个快应用调试器去扫 IDE 中提供的二维码就可以实现预览了。

1. 给自己的手机安装调试必须的环境 首先手机连接到电脑上，自己的手机一定要开启开发者模式，而且要能够运行被调试。手机连接到电脑之后，会弹出 USB 用于什么的诸多选项：
   • 仅充电
   • 传输文件/Android Auto
   • 传输照片
   • USB网络共享
   • MIDI

   一定要选择 传输文件/Android Auto

2. 然后去电脑端的 IDE,按照图示去安装必须的快应用调试器：
3. 此时，手机上会弹出安装引导，会安装两个程序：快应用预览版，快应用调试器，都安装上，然后打开快应用调试器，关闭开启USB调试这个按钮
4. 然后点击下面的按钮扫码安装，去扫码 IDE 中提供的二维码：
5. 手机上预览快应用如下效果：

2.2 使用 VSCode

npm install -g hap-toolkit

hap -v

# 这会生成最基础的工程目录文件
npm init quickapp-demo

cd quickapp-demo

npm install

# watch可以根据文件变化重新生成rpk最新文件
npm run build && npm run watch

npm run server

通常情况下，npm run server 不会生成 dist 目录。这两个命令在快应用（Quick App）开发中有明确的分工： npm run build：负责编译打包。它会扫描源代码，进行转换、压缩，并在项目根目录下生成 dist 文件夹，里面包含 .rpk 或 .rpks 文件。 npm run server：负责启动调试服务器。它的作用是启动一个本地 Web 服务，通常会生成一个 QR 码，方便在手机调试器上扫码查看效果。它默认假设已经有了编译好的文件，或者是在内存中处理数据，而不一定会向磁盘写入新的 dist 目录

同样vscode里面，也可以进行三种方式的调试：

• 手机通过usb调试
• 手机扫码调试(局域网)
• 电脑本机浏览器预览调试

三、产品与布局

四、使用 uniapp 框架开发快应用(暂无)