基础语法

一、创建 uni-app 项目

方式一：

HBuilderX 创建 uni-app 项目步骤：

点工具栏里的文件 -> 新建 -> 项目（快捷键 Ctrl+N）
选择 uni-app 类型，输入工程名，选择模板，选择 Vue 版本，点击创建即可

方式二：

Vue-CLI 命令行创建

全局安装 Vue-CLI （目前仍推荐使用 vue-cli 4.x ）：npm install -g @vue/cli@4
创建项目：vue create -p dcloudio/uni-preset-vue my-project-name

二、运行 uni-app

浏览器运行

选中 uniapp 项目，点击工具栏的运行 -> 运行到浏览器 -> 选择浏览器，即可体验 uni-app 的 web 版。

微信开发者工具运行

选中 uniapp 项目，点击工具栏的运行 -> 运行到小程序模拟器 -> 微信开发者工具
其它注意事项：
- 微信开发者工具开启服务端口：小程序开发工具设置 -> 安全（目的是让 HBuilder 启动微信开发者工具）
- 第一次使用，需配置微信开发者工具的安装路径

运行 App 到手机或模拟器

先连接真机或者模拟器
选中 uniapp 项目，点击工具栏的运行 -> 运行 App 到手机或模拟器
其他注意事项:
- Mac 电脑可以安装 Xcode
- Window 电脑可以安装 mumu 模拟器

三、目录结构

四、开发规范

为了实现多端兼容，综合考虑编译速度、运行性能等因素，uni-app 约定了如下开发规范：

页面文件遵循 Vue 单文件组件 (SFC) 规范（https://vue-loader.vuejs.org/zh/spec.html）
组件标签靠近小程序规范，详见 uni-app 组件规范（https://uniapp.dcloud.net.cn/component/）
接口能力（JS API）靠近微信小程序规范，但需将前缀 wx 替换为 uni，详见 uni-app 接口规范（https://uniapp.dcloud.net.cn/api/）
数据绑定及事件处理同 Vue.js 规范，同时补充了 App 及页面的生命周期
为兼容多端运行，建议使用 flex 布局进行开发，推荐使用 rpx 单位（750 设计稿）
文档直接查看 uni-app 的官网文档： https://uniapp.dcloud.net.cn/

五、main.js

main.js 是 uni-app 的入口文件，主要作用是：

初始化 vue 实例。
定义全局组件。
定义全局属性。
安装插件，如：pinia、vuex 等。

六、App.vue

App.vue 入口组件

App.vue 是 uni-app 的入口组件，所有页面都是在 App.vue 下进行切换
App.vue 本身不是页面，这里不能编写视图元素，也就是没有

App.vue 的作用：

应用的生命周期
编写全局样式
定义全局数据 globalData

注意：应用生命的周期仅可在 App.vue 中监听，在页面监听无效。

七、全局和局部样式

全局样式

App.vue 中 style 的样式为全局样式，作用于每一个页面（style 标签不支持 scoped，写了导致样式无效）
App.vue 中通过 @import 语句可以导入外联样式，一样作用于每一个页面。
uni.scss 文件也是用来编写全局公共样式，通常用来定义全局变量
uni.scss 中通过 @import 语句可以导入外联样式，一样作用于每一个页面

局部样式

在 pages 目录下 vue 文件的 style 样式为局部样式，只作用对应的页面，并会覆盖 App.vue 中相同的选择器
vue 文件中的 style 标签支持 scss 等预处理器，比如：安装 dart-sass 插件后，style 标签便可支持 scss 写样式了
style 标签不支持 scoped，不需写

八、uni.scss

uni.scss 全局样式文件

为了方便整体控制应用风格。默认定义了 uni-app 框架内置全局变量，当然也可以存放自定义的全局变量等
在 uni.scss 中定义的变量，我们无需 @import 就可以在任意组件中直接使用
使用 uni.scss 中的变量，需在 HBuilderX 里面安装 scss 插件（dart-sass 插件）
然后在该组件的 style 上加 lang=“scss”，重启即可生效

注意事项：

这里的 uni-app 框架内置变量和后面 uni-ui 组件库的内置变量是不一样的
uni.scss 定义的变量是全局可以直接使用，App.vue 定义的变量只能在当前组件中使用

九、页面调用接口

`getApp()` 函数

( 兼容 h5、weapp、app )：

用于获取当前应用实例，可用于获取globalData

`getCurrentPages()` 函数

( 兼容 h5、weapp、app )

用于获取当前页面栈的实例，以数组形式按栈的顺序给出
- 数组：第一个元素为首页，最后一个元素为当前页面
仅用于展示页面栈的情况，请勿修改页面栈，以免造成页面状态错误
常用方法如下图所示:

十、page.json

page.json 全局页面配置（兼容 h5、weapp、app ）

pages.json 文件用来对 uni-app 进行全局配置，类似微信小程序中 app.json
决定页面的路径、窗口样式、原生的导航栏、底部的原生 tabbar 等

十一、manifest.json

manifest.json 应用配置

Android 平台相关配置
iOS 平台相关配置、
Web 端相关的配置
微信小程序相关配置
...

十二、常用内置组件

view：视图容器。类似于 html 中的 div，用于包裹各种元素内容
text：文本组件。用于包裹文本内容
button：在小程序端的主题和在其它端的主题色不一样
image：图片。默认宽度 320px、高度 240px
- 仅支持相对路径、绝对路径，支持导入，支持 base64 码；
scrollview：可滚动视图区域，用于区域滚动。
- 使用竖向滚动时，需要给<scroll-view>一个固定高度，通过 css 设置 height
- 使用横向滚动时，需要给<scroll-view>添加 white-space: nowrap;样式，子元素设置为行内块级元素
- APP 和小程序中，请勿在<scroll-view> 中使用 map、video 等原生组件
- 小程序的<scroll-view>中也不要使用 canvas、textarea 原生组件
- 若要使用下拉刷新，建议使用页面的滚动，而不是<scroll-view>
swiper：滑块视图容器，一般用于左右滑动或上下滑动比如 banner 轮播图。
默认宽 100%，高为 150px，可设置 swiper 组件高度来修改默认高度，图片宽高可用 100%

十三、尺寸单位（rpx）

uni-app 支持的通用 css 单位包括 px、rpx（推荐单位）、vh、vw

px 即屏幕像素，rpx 是响应式像素（ responsive pixel ），可以根据屏幕宽度进行自适应
规定屏幕宽为 750rpx。如在 iPhone6 上，屏幕宽度为 375px，共有 750 个物理像素
- 则 750rpx = 375px = 750 物理像素，1rpx = 0.5px = 1 物理像素
建议：开发微信小程序时用 iPhone6 作为设计稿的标准（即：设计稿宽度为 750px）

十四、样式导入

使用@import语句可以导入外联样式（css 或 scss）
@import后跟需要导入的外联样式表的相对路径，用;表示语句结束
- 除了相对路径，默认是支持绝对路径（即@别名前缀）
- 相对路径：../../common/base.css
- 绝对路径：@/static/common/base.css

十五、背景图片

uni-app 支持使用在 css 里设置背景图片，使用方式与普通 web 项目大体相同，但需要注意以下几点：

支持 base64 格式图片，支持网络路径图片
小程序不支持在 css 中使用本地文件，包括背景图和字体文件，需转成 base64 后使用
使用本地背景图片或字体图标需注意：
- 为方便开发者，在背景图片小于 40kb 时，uni-app 编译到不支持本地背景图的平台时，会自动将其转化为 base64 格式；
- 图片大于等于 40kb，会有性能问题，不建议使用太大的背景图，如开发者必须使用，则需自己将其转换为 base64 格式使用，或将其挪到服务器上，从网络地址引用
- 本地背景图片的引用路径推荐使用以 ~@ 开头的绝对路径: background-image: url('~@/static/logo.png')

十六、字体图标

uni-app 支持使用字体图标，使用方式与普通 web 项目相同，注意事项也会背景图片一样，使用步骤如下：

先制作字体图标，比如：可以在 iconfont 网站中生成
将字体图标文件引入项目，比如：iconfont.ttf
在全局的 css 中引入字体图标，比如：App.vue

css

@font-face {
	font-family: "iconfont",
  src: url('~@/static/custom-font/iconfont.ttf').format('truetype')
}

.iconfont {
	font-family: "iconfont" !important;
  font-size: 16px;
  font-style: normal;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

.iconfont-edit:before {
	content: "\e6d6"
}

vue

<text class="iconfont icon-edit" style="font-size: 100rpx"></text>

一、扩展组件（uni-ui）

1.1、什么是 uni-ui？

uni-ui 是 DCloud 提供的一个 UI 组件库，一套基于 Vue 组件、flex 布局的跨全端 UI 框架
uni-ui 不包括 uni-app 框架提供的基础组件，而是基础组件的补充
详情：https://uniapp.dcloud.net.cn/component/uniui/uni-ui.html

1.2、安装 uni-ui 组件库

方式一：

通过 uni_modules（插件模块化规范）单独安装组件，通过 uni_modules 按需安装某个组件：

步骤 1：官网找到扩展组件清单，然后将所需要的组件导入到项目，导入后直接使用，无需 import 和注册
步骤 2：通常我们还想切换应用风格，这时可以在 uni.scss 导入 uni-ui 提供的内置 scss 变量，然后重启应用
注意：需要登录 DCloud 账号才能安装

方式二:

通过 uni_modules 导入全部组件

如想把所有 uni-ui 组件导入到项目，可以借用 Hbuilder X 插件导入
如没自动导入其他组件，可下载源码复制过去即可

方式三：

在 HBuilderX 新建 uni-app 项目时，在模板中选择 uni-ui 模板来创建项目

由于 uni-app 独特的 easycom（自动导包）技术，可以免引入、注册，就直接使用符合规则的 vue 组件

方式四：

npm 安装

在 vue-cli 项目中可用 npm 安装 uni-ui 库

1.3、定制 uni-ui 主题风格

安装 dart-sass 插件(一般都会提示，并自动安装)
在项目根目录的 uni.scss 文件引入 uni-ui 组件库的 variable.scss 变量文件，就可以使用或修改对应的 scss 变量
- @import '@/uni_modules/uni-scss/variables.scss'
变量主要定义的是主题色。

1.4、uni-forms 组件

uni-froms 组件使用步骤（类似 Element Plus 的表单组件用法）：

安装 uni-forms 等组件
uni-forms 搭建表单布局
编写表单项的验证规则
提交表单时验证表单项
重置表单

1.5、重写 uni-forms 组件样式

小程序、App 直接重写，需要添加 important
H5、App 和小程序使用：global( selector ) ，需要添加 important
H5 、App 和小程序使用：deep( selector ) ，需要添加 important

scss

.uni-forms-item__label {
	justify-content: center !important;
	color: red !important;
}

:global(.uni-forms-item__label) {
	color: purple !important;
	justify-content: center !important;
}

:deep(.uni-forms-item__label) {
	justify-content: center !important;
	color: green !important;
}

二、跨平台兼容

uni-app 能实现一套代码、多端运行，核心是通过编译器 + 运行时实现的：

编译器：将 uni-app 统一代码编译生成每个平台支持的特有代码；如在小程序平台，编译器将.vue 文件拆分生成 wxml、wxss、js 等
运行时：动态处理数据绑定、事件代理，保证 Vue 和对应宿主平台数据的一致性；

跨平台存在的问题：

uni-app 已将常用的组件、JS API 封装到框架中，开发者按照 uni-app 规范开发即可保证多平台兼容，大部分业务均可直接满足
但每个平台有自己的一些特性，因此会存在一些无法跨平台的情况
- 大量写 if else，会造成代码执行性能低下和管理混乱
- 编译到不同的工程后二次修改，会让后续升级变的很麻烦

跨平台兼容解决方案：

在 C 语言中，通过 #ifdef、#ifndef 的方式，为 windows、mac 等不同 os 编译不同的代码
uni-app 参考这个思路，为 uni-app 提供了条件编译手段，在一个工程里优雅的完成了平台个性化实现

条件编译

条件编译是用特殊的注释作为标记，在编译时根据这些特殊的注释，将注释里面的代码编译到不同平台

具体的语法：以 #ifdef 或 #ifndef 加 %PLATFORM% 开头，以 #endif 结尾

#ifdef：if defined 仅在某平台存在
#ifndef：if not defined 除了某平台，其它平台均存在
%PLATFORM%：平台名称

支持编写条件编译的文件，如下：

vue（template 、script 、style）
.js 、.ts 、pages.json
.css、.scss、.less、.stylus

例如：设置页面的标题

H5 专有 API：document.title = ''
微信小程序专有 API：wx.setNavigationBarTitle(object)

注意事项

条件编译是利用注释实现的，在不同语法里注释写法不一样

js 使用 //注释
css 使用 /* 注释 */
vue/nvue 模板里使用

条件编译 APP-PLUS 包含：APP-NVUE 和 APP-VUE

APP-PLUS-NVUE 和 APP-NVUE 没什么区别，为了简写后面出了 APP-NVUE

使用条件编译请保证编译前和编译后文件的正确性，比如 json 文件中不能有多余的逗号

Android 和 iOS 不支持条件编译，如需区分 Android、iOS 平台，请通过调用 uni.getSystemInfo 来获取平台信息

微信小程序主题色是绿色，而百度支付宝小程序是蓝色，应用想分平台适配颜色，条件编译是代码量最低、最容易维护的

三、新建 Page 页面

uni-app 页面是编写在 pages 目录下

可直接在 uni-app 项目上右键“新建页面”，HBuilderX 会自动在 pages.json 中完成页面注册。
HBuilderX 还内置了常用的页面模板（如图文列表、商品列表等），这些模板可以大幅提升你的开发效率。

注意事项：

每次新建页面，需在 pages.json 中配置 pages 列表（手动才需配置）
未在 pages.json -> pages 中配置的页面，uni-app 会在编译阶段进行忽略。

删除页面：

删除.vue 文件和 pages.json 中对应的配置

配置 tabBar

color
selectedColor
list -> pagePath、text、iconPath、selectedIconPath

四、页面路由

uni-app 有两种页面路由跳转方式：使用 navigator 组件跳转、调用 API 跳转（类似小程序，与 vue-router 不同）

组件：navigator
API：navigateTo、redirectTo、navigateBack、switchTab

五、页面间通讯

在 uni-app 中，常见页面通讯方式：

方式一：url 查询字符串和 EventChannel
方式二：使用事件总线
方式三：全局数据 globalData
方式四：本地数据存储
方式五：Vuex 和 Pinia，状态管理库。

方式一：

url 传递数据

直接在 url 后面通过查询字符串的方式拼接
- 如 url 查询字符串出现特殊字符等格式，需编码
然后可在 onLoad 生命周期中获取 url 传递的参数

EventChannel 对象的获取方式

Options 语法：this.getOpenerEventChannel()
Composition 语法：getCurrentInstance().proxy. getOpenerEventChannel()

方式二：

uni.$emit( eventName, OBJECT ) 触发全局的自定义事件
uni.$on( eventName, callback ) 监听全局的自定义事件。由 uni.$emit 触发
uni.$once( eventName, callback ) 只监听一次全局的自定义事件。由 uni.$emit 触发
uni.$off( eventName, callback ) 移除全局自定义事件监听器
- 如果没有提供参数，则移除所有的事件监听器；

注意事项：

需先监听，再触发事件，比如：你在 A 界面触发，然后跳转到 B 页面后才监听是不行的
通常 on 和 off 是同时使用，可以避免多次重复监听
适合页面返回传递参数、适合跨组件通讯，不适合界面跳转传递参数

六、页面生命周期

uni-app 常用的页面生命周期函数：

onLoad(options) -> onLoad
onShow -> onShow
onReady -> onReady
onHide -> onHide
onUnload -> onUnload
onPullDownRefresh -> onPullDownRefresh
onReachBottom -> onReachBottom
更多： https://uniapp.dcloud.net.cn/tutorial/page.html#lifecycle

注意事项：

页面可以使用 Vue 组件生命周期吗？可以的
页面滚动才会触发 onReachBottom 回调，如果自行通过 overflow 实现的滚动不会触发 onReachBottom 回调

七、网络请求

uni.request(OBJECT) 发起网络请求

登录各个小程序管理后台，给网络相关的 API 配置合法域名（域名白名单）
微信小程序开发工具，在开发阶段可以配置：不校验合法域名
运行到手机时，资源没有出来时可以打开手机的调试模式
请求的 header 中 content-type 默认为 application/json

八、数据缓存

uni.setStorage(OBJECT)

将数据存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个异步接口

uni.setStorageSync(KEY, DATA)

将 data 存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个同步接口

uni.getStorage(OBJECT)

从本地缓存中异步获取指定 key 对应的内容

uni.getStorageSync(KEY)

从本地缓存中同步获取指定 key 对应的内容

uni.removeStorage(OBJECT)

从本地缓存中异步移除指定 key

uni.removeStorageSync(KEY)

从本地缓存中同步移除指定 key

九、组件（Component）

uni-app 组件 Vue 标准组件基本相同，但是也有一点区别，比如：

传统 vue 组件，需创建组件、引用、注册，三个步骤后才能使用组件， easycom 组件模式将其精简为一步
easycom 组件规范：
- 组件需符合 components/组件名称/组件名称.vue 的目录结构
- 符合以上目录结构的就可不用引用、注册，直接在页面中使用该组件了

组件生命周期

uni-app 组件支持的生命周期，与 Vue 组件的生命周期相同

组件中可以使用页面的生命周期吗?

在 Options API 语法：组件中不支持使用页面生命周期。
在 Composition API 语法：组件中支持页面生命周期，不同端支持情况有差异。

十、Pinia

Pinia（发音为 /piːnjʌ/，如英语中的 peenya）是 Vue 的存储库，它允许跨组件、页面共享状态。

uni-app 内置了 Pinia，使用 HBuilder X 不需要手动安装，直接使用即可

使用 CLI 需要手动安装，执行 yarn add pinia 或 npm install pinia

Pinia 的初体验，步骤如下：

第一步：在 main.js 中安装 Pinia 插件
- app.use(Pinia.createPinia())
第二步：接着创建一个 store
第三步：然后在组件中就可以直接使用了

基础语法 ​

一、创建 uni-app 项目 ​

方式一： ​

方式二： ​

二、运行 uni-app ​

浏览器运行 ​

微信开发者工具运行 ​

运行 App 到手机或模拟器 ​

三、目录结构 ​

四、开发规范 ​

五、main.js ​

六、App.vue ​

App.vue 入口组件 ​

App.vue 的作用： ​

七、全局和局部样式 ​

全局样式 ​

局部样式 ​

八、uni.scss ​

九、页面调用接口 ​

getApp() 函数 ​

getCurrentPages() 函数 ​

十、page.json ​

十一、manifest.json ​

十二、常用内置组件 ​

十三、尺寸单位（rpx） ​

十四、样式导入 ​

十五、背景图片 ​

十六、字体图标 ​

一、扩展组件（uni-ui） ​

1.1、什么是 uni-ui？ ​

1.2、安装 uni-ui 组件库 ​

方式一： ​

方式二: ​

方式三： ​

方式四： ​

1.3、定制 uni-ui 主题风格 ​

1.4、uni-forms 组件 ​

1.5、重写 uni-forms 组件样式 ​

二、跨平台兼容 ​

条件编译 ​

注意事项 ​

三、新建 Page 页面 ​

四、页面路由 ​

五、页面间通讯 ​

方式一： ​

方式二： ​

六、页面生命周期 ​

七、网络请求 ​

八、数据缓存 ​

uni.setStorage(OBJECT) ​

uni.setStorageSync(KEY, DATA) ​

uni.getStorage(OBJECT) ​

uni.getStorageSync(KEY) ​

uni.removeStorage(OBJECT) ​

uni.removeStorageSync(KEY) ​

九、组件（Component） ​

组件生命周期 ​

十、Pinia ​

基础语法

一、创建 uni-app 项目

方式一：

方式二：

二、运行 uni-app

浏览器运行

微信开发者工具运行

运行 App 到手机或模拟器

三、目录结构

四、开发规范

五、main.js

六、App.vue

App.vue 入口组件

App.vue 的作用：

七、全局和局部样式

全局样式

局部样式

八、uni.scss

九、页面调用接口

`getApp()` 函数

`getCurrentPages()` 函数

十、page.json

十一、manifest.json

十二、常用内置组件

十三、尺寸单位（rpx）

十四、样式导入

十五、背景图片

十六、字体图标

一、扩展组件（uni-ui）

1.1、什么是 uni-ui？

1.2、安装 uni-ui 组件库

方式一：

方式二:

方式三：

方式四：

1.3、定制 uni-ui 主题风格

1.4、uni-forms 组件

1.5、重写 uni-forms 组件样式

二、跨平台兼容

条件编译

注意事项

三、新建 Page 页面

四、页面路由

五、页面间通讯

方式一：

方式二：

六、页面生命周期

七、网络请求

八、数据缓存

uni.setStorage(OBJECT)

uni.setStorageSync(KEY, DATA)

uni.getStorage(OBJECT)

uni.getStorageSync(KEY)

uni.removeStorage(OBJECT)

uni.removeStorageSync(KEY)

九、组件（Component）

组件生命周期

十、Pinia