85_uni-app框架基础

摘要：跨越了后端的深水区，我们终于来到了用户直接触碰的彼岸——前端。在构建全栈 AI 工具平台的过程中，如何以一套代码高效覆盖 iOS、Android、微信小程序、H5 等多个平台，是降低研发成本、快速抢占市场的关键。uni-app 作为基于 Vue.js 的跨端框架，凭借其庞大的生态和优秀的性能，成为了我们的首选。

本章将不仅仅是 API 的罗列，更是一次深入 uni-app 骨架的解剖之旅。我们将从工程目录的每一个文件讲起，揭示 pages.json 背后的路由调度逻辑，剖析组件化开发的“easycom”黑科技，探讨 rpx 响应式布局的数学原理，并建立一套严谨的工程化开发规范。无论你是 Vue 老手还是小程序新人，这里都有你未曾注意过的底层细节。

关联的小程序样例：薄荷百宝箱

164.1 uni-app 项目结构

当你第一次创建一个 uni-app 项目，无论是通过 HBuilderX 可视化创建，还是通过 Vue CLI 命令行创建，映入眼帘的是一套约定俗成的目录结构。很多新手往往忽视了对目录结构的深度理解，导致项目后期代码混乱、资源引用报错、分包困难。

1. 为什么目录结构如此重要？

在传统的 Web 开发（如 React/Vue 单页应用）中，目录结构往往比较自由，只要 Webpack/Vite 配置得当，文件放哪里都能跑。但在 uni-app 中，目录结构即配置。

uni-app 的编译器（基于 Webpack 或 Vite）深度依赖特定的目录约定来实现跨端编译。例如，它会自动寻找 pages 目录下的 .vue 文件来生成路由，自动寻找 static 目录来复制静态资源。如果你打破了这些约定，编译器就会失效，或者在某些特定平台（如微信小程序）上出现诡异的 Bug。

我们可以把一个 uni-app 项目比作建造一座大楼：

pages/：这是大楼里的房间。每一个 Vue 文件就是一个可供人居住（交互）的房间。
static/：这是仓库。存放不会被编译器修改的装修材料（图片、字体）。
components/：这是预制件。生产好的门窗、家具，可以在不同房间里重复使用。
pages.json：这是楼层导览图。告诉保安（路由系统）哪个房间在几楼，怎么走。
manifest.json：这是施工许可证。定义了大楼的名字、图标、权限，以及它属于哪个小区（AppID）。

2. 标准目录详解与工程实践

一个生产级的 AI 工具平台项目，其目录结构应该更加严谨。以下是我们推荐的结构：

Plaintext

ai-tools-app/
├── .hbuilderx/             # HBuilderX 专属配置（如代码片段）
├── common/                 # [规范] 公共工具库 (非组件)
│   ├── api/                # API 接口定义
│   ├── utils/              # 工具函数 (日期格式化、防抖节流)
│   ├── config.js           # 全局配置 (域名、环境开关)
│   └── request.js          # 封装的网络请求拦截器
├── components/             # [核心] 全局通用组件
│   └── uni-nav-bar/        # 遵循 easycom 规范的组件目录
│       └── uni-nav-bar.vue 
├── hybrid/                 # [进阶] 存放本地 HTML 文件 (用于 WebView)
├── pages/                  # [核心] 业务页面
│   ├── index/              # 首页模块
│   │   └── index.vue
│   ├── user/               # 用户中心模块
│   │   └── user.vue
│   └── tools/              # AI 工具模块
│       ├── chat.vue
│       └── ocr.vue
├── static/                 # [核心] 静态资源 (图片、字体)
│   ├── tabbar/             # 底部导航图标
│   └── logo.png
├── store/                  # Vuex 或 Pinia 状态管理
├── unpackage/              # 编译后的输出目录 (不要提交到 Git)
├── App.vue                 # 应用入口组件 (生命周期、全局样式)
├── main.js                 # 入口文件 (挂载插件、初始化)
├── manifest.json           # 跨端配置文件 (AppID, 权限, 图标)
├── pages.json              # 路由与页面配置
└── uni.scss                # 内置的常用样式变量

3. 关键目录的底层原理

`static` 目录的特殊性

在编译过程中，static 目录下的文件会被原封不动地拷贝到输出目录。

引用方式：必须使用绝对路径 /static/logo.png。
差异：在 Vue CLI 项目中通常叫 public 或 assets。但在 uni-app 中，assets 下的图片会被 base64 编码或哈希化，而 static 不会。
避坑指南：
不要在 static 里放 JS/CSS 文件并试图 import，因为它们不会被 Webpack 编译（ES6 转 ES5、压缩等都会失效）。
小程序包体积有限制（通常 2MB）。大图严禁放在 static，必须传到 OSS（对象存储）使用网络路径。

`unpackage` 目录

这是编译输出的产物。

dist/dev/mp-weixin：开发环境微信小程序代码。
dist/build/app-plus：生产环境 App 代码。
注意：在 .gitignore 中必须忽略此目录，否则会导致 Git 仓库体积爆炸，且合并代码时产生无数冲突。

4. `App.vue` vs `main.js`

新手容易混淆这两个入口。

main.js：是 JS 逻辑的入口。
它是应用启动的第一步。
负责初始化 Vue 实例、引入全局插件（uView, Pinia）、挂载全局方法。
它不包含界面渲染逻辑。
App.vue：是 组件/界面的入口。
它是所有页面的根组件（Root Component）。
没有 <template>：因为它不渲染具体内容，内容由 <page> 接管。
应用生命周期：onLaunch（启动）、onShow（前台）、onHide（后台）都在这里定义。
全局样式：这里的 <style> 标签中的样式会作用于所有页面（非 scoped）。

164.2 pages.json 配置

pages.json 是 uni-app 中最独特、最核心的配置文件。它不仅仅是路由表，更是整个应用的外观控制中心。它接管了传统 Web 开发中 vue-router 的配置、index.html 的 title 设置以及原生 App 的导航栏样式。

1. 为什么要用 JSON 而不是 JS？

很多 React/Vue 开发者习惯了用 JS 代码动态配置路由，看到 pages.json 这种死板的 JSON 格式会感到不适。

原因：

原生性能：uni-app 的设计目标是跨端。在小程序和 App 端，底层的原生引擎需要在 JS 引擎启动之前就读取到页面配置，以便预加载界面、绘制原生导航栏（Native Navigation Bar）。JSON 解析速度极快，且不需要运行 JS 逻辑。
静态分析：编译器需要根据 pages.json 来分析哪些页面属于主包，哪些属于分包，从而进行代码分割（Code Splitting）。如果是动态 JS，编译器很难静态推导。

2. 核心配置项解析

`globalStyle`：全局外观

这是“默认皮肤”。如果某个页面没有单独配置，就会使用这里的样式。

JSON

"globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "AI工具箱",
    "navigationBarBackgroundColor": "#FFFFFF",
    "backgroundColor": "#F8F8F8",
    "usingComponents": {} // 小程序特有，全局引用自定义组件
}

原理：在 H5 端，这些配置会被编译成 CSS 样式或 DOM 操作；在小程序和 App 端，这些会被映射为原生 View 的属性，性能远高于 WebView 渲染的导航栏。

`pages`：页面注册

这是一个数组，数组的第一项就是应用的首页。

JSON

"pages": [
    {
        "path": "pages/index/index",
        "style": {
            "navigationBarTitleText": "首页",
            "enablePullDownRefresh": true // 开启原生下拉刷新
        }
    },
    {
        "path": "pages/user/user",
        "style": {
            "navigationBarTitleText": "个人中心",
            "navigationStyle": "custom" // 重点：自定义导航栏
        }
    }
]

自定义导航栏 (custom)：这是 AI 工具类 App 最常用的配置。为了实现沉浸式体验或在导航栏放搜索框，我们需要隐藏原生导航栏，使用前端组件自己画一个。注意：开启后，左上角的胶囊按钮（小程序）依然存在，需通过 uni.getMenuButtonBoundingClientRect() 计算避让距离。

`tabBar`：底部导航

底部导航栏是顶级入口。uni-app 提供了原生的 TabBar 支持。

JSON

"tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#007AFF",
    "borderStyle": "black",
    "backgroundColor": "#FFFFFF",
    "list": [
        {
            "pagePath": "pages/index/index",
            "iconPath": "static/tabbar/home.png",
            "selectedIconPath": "static/tabbar/home-active.png",
            "text": "工具"
        },
        {
            "pagePath": "pages/user/user",
            "iconPath": "static/tabbar/user.png",
            "selectedIconPath": "static/tabbar/user-active.png",
            "text": "我的"
        }
    ]
}

坑点：
pagePath 必须是在 pages 数组中定义过的。
iconPath 必须是本地路径，不能是网络图片或 base64。
Tabbar 页面只能通过 uni.switchTab 跳转，不能用 MapsTo。

3. 分包配置 (`subPackages`)

随着 AI 工具越来越多，小程序的主包体积很容易超过 2MB 限制。这时必须使用分包。

JSON

"subPackages": [
    {
        "root": "pages/tools",
        "pages": [
            {
                "path": "chat",
                "style": { ... }
            },
            {
                "path": "ocr",
                "style": { ... }
            }
        ]
    }
]

原理：用户打开 App 时，只下载主包（首页、公共库）。当用户点击“AI 聊天”工具时，系统才去下载 pages/tools 分包。
preloadRule：分包预下载。可以在用户浏览首页时，悄悄下载分包，提升进入速度。

164.3 页面路由管理

在 uni-app 中，路由管理不像 Vue Router 那样由开发者手动实例化 Router 对象，而是由框架接管，提供了一套类似小程序原生的 API。

1. 路由栈模型 (Routing Stack)

理解页面栈是掌握路由的关键。uni-app 维护了一个数组来存储当前打开的页面。

MapsTo (进栈)：保留当前页面，跳转到应用内的某个页面。栈长度 +1。
场景：从列表页点击进入详情页。
限制：小程序限制栈深度为 10 层。超过后无法跳转。
redirectTo (替换)：关闭当前页面，跳转到应用内的某个页面。栈长度不变（替换栈顶）。
场景：表单提交成功后，跳转到成功结果页（不允许返回表单页）。
MapsBack (出栈)：关闭当前页面，返回上一页面或多级页面。栈长度 -1 或 -N。
场景：详情页点击左上角返回。
switchTab (清空栈)：跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。
场景：点击底部导航。
reLaunch (重置栈)：关闭所有页面，打开到应用内的某个页面。
场景：退出登录后跳转到登录页，或者支付成功后回首页。

2. 参数传递与编解码

传递参数：

uni-app 的参数传递非常原始，通过 URL Query String 传递。

JavaScript

// 跳转
uni.navigateTo({
    url: '/pages/tools/chat?model=gpt4&temperature=0.7'
});

// 接收 (在目标页面的 onLoad 生命周期)
onLoad(options) {
    console.log(options.model); // "gpt4"
    console.log(options.temperature); // "0.7" (注意是字符串)
}

复杂参数陷阱：

如果传递的参数包含特殊字符（如 URL、JSON 字符串），必须使用 encodeURIComponent。

JavaScript

// ❌ 错误：如果 url 包含 ? 或 & 会截断
let fileUrl = 'https://oss.com/file?id=1&type=img';
uni.navigateTo({ url: '/pages/view?url=' + fileUrl }); 

// ✅ 正确
uni.navigateTo({ url: '/pages/view?url=' + encodeURIComponent(fileUrl) });

// 接收端解码
onLoad(options) {
    let url = decodeURIComponent(options.url);
}

超长参数解决方案：

URL 有长度限制。如果要传递一个巨大的对象（比如 AI 生成的 2000 字长文），不要通过 URL 传。

方案 A：存 Vuex/Pinia 或 uni.setStorage，只传 ID。
方案 B：使用 EventChannel（页面间通讯通道）。

JavaScript

// 发送页
uni.navigateTo({
    url: '/pages/result',
    success: function(res) {
        // 通过 eventChannel 向被打开页面传送数据
        res.eventChannel.emit('acceptData', { data: bigDataObj });
    }
});

// 接收页 (onLoad)
const instance = getCurrentInstance().proxy;
const eventChannel = instance.getOpenerEventChannel();
eventChannel.on('acceptData', function(data) {
    console.log(data);
});

164.4 组件使用规范

uni-app 的组件系统是 Vue 组件与小程序组件的混合体。它既支持 .vue 的单文件组件写法，又内置了一套对标微信小程序的标签体系。

1. 内置组件 vs HTML 标签

在 uni-app 中，请忘记 <div>, <span>, <img>。虽然在 H5 端它们能跑，但在小程序和 App 端，它们是不合法的。

<div> -> <view>：这是最基础的容器。在 App 端，它对应原生的 View/ViewGroup；在小程序端对应 <view>。它默认是 display: flex 还是 block 取决于平台，建议显式写 Flex。
<span> -> <text>：文本必须包在 <text> 中。只有 <text> 包裹的内容才能长按选中，也只有 <text> 下的文本节点才能直接换行。
<img> -> <image>：功能更强大，支持懒加载、模式裁剪（mode）。注意：<image> 默认有 320x240 的宽高，不写宽高会导致变形。

2. easycom 组件规范

在传统 Vue 开发中，使用组件需要三步：import -> components 注册 -> template 使用。

uni-app 推出了 easycom 机制，实现了自动扫描，按需引用。

规则：

只要组件文件符合 components/组件名称/组件名称.vue 的目录结构，就可以直接在页面中使用 <组件名称 />，无需任何引入和注册。

示例：

文件路径：components/ai-input-box/ai-input-box.vue

页面使用：

HTML

<template>
    <view>
        <ai-input-box placeholder="请输入 Prompt"></ai-input-box>
    </view>
</template>

优势：

开发效率：少写大量样板代码。
性能优化：easycom 是按需打包的。如果你写了引用但没在 Template 里用，打包时会自动剔除该组件代码，减小包体积。

3. 组件生命周期

这是一个常见的面试坑点。

页面 (Page)：拥有 onLoad, onShow, onPullDownRefresh 等生命周期。
组件 (Component)：没有 onLoad！组件只有 Vue 的标准生命周期：created, mounted, unmounted。

常见错误：

JavaScript

// 在组件里写 onLoad 接收参数 —— 永远不会执行！
export default {
    onLoad(opts) { 
        console.log(opts); // ❌ 无效
    },
    mounted() {
        console.log("组件挂载完成"); // ✅ 有效
    }
}

如果组件需要获取页面参数，通常通过 props 从父页面传入，或者在 mounted 中通过 getCurrentPages() 获取当前页面栈来分析参数（不推荐，耦合度太高）。

164.5 样式编写规范

前端开发的一半时间在写 CSS。在跨端开发中，屏幕适配是最大的痛点。

1. 响应式单位 `rpx`

uni-app 引入了 rpx (responsive pixel) 单位，这源自微信小程序。

核心定义：规定屏幕基准宽度为 750rpx。

iPhone 6 (屏幕宽 375px): 750rpx = 375px => 1rpx = 0.5px
iPhone 14 Pro Max (屏幕宽 430px): 750rpx = 430px => 1rpx ≈ 0.57px

为什么要用 rpx？

设计师通常按 iPhone 6/7/8 (750px 物理像素) 出设计稿。开发者拿到设计稿，量出来是 100px 的宽度，代码里直接写 width: 100rpx 即可。无需换算，即可适配所有宽度的手机屏幕。

最佳实践：

布局、间距、字体大小：通通使用 rpx。
边框：1px 的边框建议使用 1px 而不是 2rpx，因为在某些高分屏下 1px 能渲染出物理上的 1 像素（极细），而 rpx 计算后可能产生亚像素模糊。

2. 样式隔离 (Scoped)

Vue 的

关联的小程序样例：薄荷百宝箱

164.1 uni-app 项目结构

1. 为什么目录结构如此重要？

2. 标准目录详解与工程实践

3. 关键目录的底层原理

static 目录的特殊性

unpackage 目录

4. App.vue vs main.js

164.2 pages.json 配置

1. 为什么要用 JSON 而不是 JS？

2. 核心配置项解析

globalStyle：全局外观

pages：页面注册

tabBar：底部导航

3. 分包配置 (subPackages)

164.3 页面路由管理

1. 路由栈模型 (Routing Stack)

2. 参数传递与编解码

164.4 组件使用规范

1. 内置组件 vs HTML 标签

2. easycom 组件规范

3. 组件生命周期

164.5 样式编写规范

1. 响应式单位 rpx

2. 样式隔离 (Scoped)

`static` 目录的特殊性

`unpackage` 目录

4. `App.vue` vs `main.js`

`globalStyle`：全局外观

`pages`：页面注册

`tabBar`：底部导航

3. 分包配置 (`subPackages`)

1. 响应式单位 `rpx`