1.初识uniapp

Uniapp 入门实战笔记

核心结论：Uniapp 是一套跨端开发框架，可快速构建微信/抖音/支付宝等小程序、iOS/Android App 及 H5，核心优势是“一次开发、多端部署”，搭配 HbuilderX 工具效率极高。

1. 初识 Uniapp

• 核心能力：支持多端输出，包括微信/抖音/支付宝/百度等主流小程序、iOS/Android 原生 App、H5 网页，无需为不同平台单独开发。

• 核心优势：基于 Vue 语法，学习成本低；内置丰富组件和 API，开发效率高；跨端兼容性强，减少适配工作量。

• 适用场景：快速迭代的创业项目、多端同步上线的产品、中小型应用开发。

---

2. 开发工具：HbuilderX

2.1 下载与安装

• 官网地址：HbuilderX 官方下载

• 版本选择：优先下载“正式版”（稳定），需体验新功能可选择“Alpha 版”。

• 安装方式：下载后解压压缩包，无需复杂安装，双击 HbuilderX.exe 即可启动（建议创建桌面快捷方式）。

2.2 必备插件（提升开发效率）

• uniapp 语法提示：默认自带，若未启用可在「工具 → 插件安装」中搜索启用。

• SCSS 编译插件：支持 SCSS 语法解析，安装后需重启工具生效。

• 小程序开发者工具关联插件：自动关联各平台开发者工具，减少手动配置。

---

3. 新建 Uniapp 项目

3.1 项目创建步骤

1. 启动 HbuilderX，点击顶部菜单栏「文件 → 新建 → 项目」。

2. 项目类型选择「uni-app」，输入项目名称、选择保存路径。

3. 模板选择「默认模板」（或根据需求选择“空白模板”“Hello UniApp 模板”）。

4. 勾选对应平台：开发 App 需勾选「APP 端」，开发小程序需勾选对应平台（如「微信小程序」「抖音小程序」）。

5. 点击「创建」，等待项目初始化完成。

3.2 项目类型说明

• 默认模板：包含基础目录结构和示例页面，适合新手入门。

• 空白模板：仅保留核心目录，无多余代码，适合纯净项目开发。

• Hello UniApp 模板：包含丰富的组件示例和 API 演示，适合学习功能用法。

---

4. 项目目录结构详解

项目根目录
├── pages          # 页面文件存放目录（核心目录）
│   └── index      # 首页文件夹（每个页面对应一个同名文件夹）
│       └── index.vue  # 首页核心文件（模板+逻辑+样式）
├── static         # 静态资源目录（图片、字体等，不会被编译）
├── App.vue        # 应用根组件（全局样式、全局生命周期）
├── main.js        # 应用入口文件（初始化 Vue 实例、配置全局挂载）
├── pages.json     # 页面路由配置（页面路径、导航栏样式、窗口配置）
├── manifest.json  # 项目配置文件（多端权限、App 图标、小程序配置等）
└── uni.scss       # 全局样式变量文件（可定义 SCSS 全局变量）

关键目录说明

• pages：所有页面必须放在此目录下，每个页面需创建同名文件夹，包含 .vue 文件。

• static：存放图片、视频等静态资源，引用时路径直接写 static/xxx.png。

• pages.json：控制页面路由和窗口表现，是 Uniapp 核心配置文件。

• manifest.json：配置 App 权限（如相机、定位）、小程序 AppID、H5 配置等。

---

5. 运行项目（多端调试）

5.1 运行到内置浏览器（快速调试）

1. 选中项目根目录，点击顶部菜单栏「运行 → 运行到浏览器 → 内置浏览器」。

2. 工具会自动编译项目，内置浏览器中实时展示页面效果，修改代码后自动刷新。

5.2 运行到小程序开发者工具

前置配置（以微信小程序为例）

1. 下载安装「微信开发者工具」，并登录微信账号。

2. 打开微信开发者工具，点击「设置 → 安全设置 → 服务端口」，开启服务端口（关键步骤）。

3. 在 HbuilderX 中，点击「运行 → 运行到小程序模拟器 → 微信开发者工具」。

4. 首次运行需配置微信开发者工具路径：「工具 → 设置 → 运行配置 → 微信开发者工具路径」，选择安装目录下的 wechatdevtools.exe。

其他小程序（抖音/支付宝）

• 流程与微信小程序一致，需先安装对应平台的开发者工具，开启服务端口，再在 HbuilderX 中选择对应运行目标。

5.3 运行到真机（App 调试）

1. 手机开启「USB 调试模式」（安卓：设置 → 关于手机 → 连续点击版本号；iOS：设置 → 开发者选项 → 开启 USB 调试）。

2. 手机连接电脑，HbuilderX 会自动识别设备。

3. 点击「运行 → 运行到手机或模拟器 → 选择已连接的手机」，工具会自动打包并安装 App 到手机，实时调试。

---

6. 页面语法与基础结构

Uniapp 页面基于 Vue 单文件组件（SFC），每个页面由 template（模板）、script（逻辑）、style（样式）三部分组成。

6.1 核心语法规则

• 模板部分：最外层必须包裹 <template> 标签，且只能有一个根节点（通常用 <view>）。

• 标签兼容：避免使用 div、h1-h6、span 等 HTML 标签，小程序/App 兼容性差；优先使用 Uniapp 内置组件（view、text、image 等）。

• 样式单位：推荐使用 rpx（响应式像素），自动适配不同屏幕尺寸（1rpx = 屏幕宽度/750）。

• 样式隔离：style 标签添加 scoped 属性，避免样式污染（默认不隔离，需手动添加）。

6.2 基本结构示例（完整可运行）

<template>
  <!-- 根节点必须唯一，用view替代div -->
  <view class="layout">
    <view class="box1">我是box1（块级元素）</view>
    <text class="text1" selectable>我是可复制文本</text>
  </view>
</template>

<script>

</script>

<style lang="scss" scoped>
/* 样式部分，支持scss（需安装插件），scoped隔离样式 */
.layout {
  padding: 20rpx;
  .box1 {
    border: 1px solid #008c8c;
    padding: 15rpx;
    margin-bottom: 20rpx;
  }
  .text1 {
    color: #333;
    font-size: 28rpx;
  }
}
</style>

6.3 创建新页面

1. 右键点击 pages 文件夹 → 「新建页面」。

2. 输入页面名称（如 mine），勾选「创建同名目录」「在pages.json中注册」。

3. 点击「创建」，工具会自动生成 mine 文件夹及 mine.vue 文件，并在 pages.json 中添加路由配置。

6.4 路由配置（pages.json）

{
  "pages": [
    // 首页（第一个页面为默认启动页）
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页", // 导航栏标题
        "navigationBarBackgroundColor": "#008c8c" // 导航栏背景色
      }
    },
    // 新创建的我的页面
    {
      "path": "pages/mine/mine",
      "style": {
        "navigationBarTitleText": "我的"
      }
    }
  ],
  "globalStyle": {
    // 全局样式配置（所有页面默认继承）
    "navigationBarTextStyle": "white", // 导航栏文字颜色（black/white）
    "backgroundColor": "#f5f5f5" // 页面背景色
  }
}

---

7. 常用内置组件（重点）

Uniapp 提供丰富的内置组件，无需引入即可使用，适配多端平台。

7.1 核心组件（必学）

组件名	作用	核心属性	示例用法
view	布局容器（替代div）	class、hover-class（点击态）	<view class="box" hover-class="box-active">内容</view>
text	文本容器（替代span）	selectable（是否可复制）、space（空格处理）	<text selectable>可复制文本</text>
button	按钮	type（primary/default/warn）、size	<button type="primary" @click="handleClick">提交</button>
image	图片加载	src（路径）、mode（裁剪模式）	<image src="/static/logo.png" mode="aspectFit"></image>
scroll-view	滚动容器	scroll-x（横向滚动）、scroll-y（纵向滚动）	<scroll-view scroll-y style="height: 300rpx;">滚动内容</scroll-view>
swiper	轮播图	indicator-dots（显示指示器）、autoplay（自动播放）	<swiper autoplay indicator-dots><swiper-item><image src=""></image></swiper-item></swiper>

7.2 组件使用注意事项

• hover-class 陷阱：父组件设置 hover-class 后，点击子组件会触发父组件的点击态，需避免嵌套使用或手动控制。

• image 组件：默认宽高为 300rpx×225rpx，需手动设置尺寸；mode="widthFix" 可保持宽高比自适应。

• scroll-view：必须设置固定高度（或通过父容器限制高度），否则无法滚动；横向滚动需设置 white-space: nowrap 且子元素为行内块级。

7.3 高效代码片段

• 快速生成 view 标签：输入 view → 按回车，自动生成 <view></view>。

• 快速生成带类名的 view：输入 view.classname → 按回车，生成 <view class="classname"></view>。

• 快速生成 text 标签：输入 text → 按回车，生成 <text></text>。

---

8. 关键注意事项（避坑指南）

1. 样式兼容性：避免使用 CSS3 高级特性（如弹性盒旧语法、渐变），部分小程序平台不支持；优先使用 Uniapp 内置样式变量。

2. API 调用：Uniapp 封装了统一的 API（如 uni.showToast、uni.request），避免使用微信小程序的 wx.xxx 或 Vue 的 axios，确保多端兼容。

3. 静态资源：图片路径建议使用绝对路径（/static/xxx.png），相对路径可能在部分平台失效；大图片建议压缩后使用，提升加载速度。

4. 生命周期：页面生命周期使用 onLoad（页面加载）、onShow（页面显示），避免使用 Vue 的 mounted（多端表现不一致）。