UniApp 互相引用

1. 绝对路径和相对路径

在日常开发中，经常会遇到使用绝对路径还是相对路径的问题，下面我们介绍下这两种路径。

1.1. 绝对路径

绝对路径：是指从项目根目录开始的完整路径。它用于指定文件或目录的确切位置。绝对路径通常以斜杠（/）开头，表示从根目录开始。

例如：

HTML

<template>
  <!-- 图片组件引用绝对路径 -->
  <image src="/static/logo.png" />
  <!-- 视频组件引用绝对路径  -->
  <video src="/static/demo.mp4" />
  <!-- 其他需要引用资源的媒体组件均可以使用绝对路径 -->
</template>
<script setup>
// 使用一个图片资源时，可以使用绝对路径
uni.getImageInfo({
  src: "/static/logo.png",
});
// 跳转页面时，可以使用绝对路径
uni.navigateTo({
  url: "/pages/login/login",
});
</script>

这里的 /static/logo.png 就是一个绝对路径，表示图片文件位于项目根目录下的 static 文件夹中。

绝对路径的优点是可以直接定位到文件的确切位置，不受当前目录的影响，通常需要动态传递的路径，我们建议使用绝对路径。

注意：

当使用 import 语句导入代码文件或静态资源时，@/ 表示项目根目录的绝对路径。如 import { add } from "@/common/utils"。

1.2. 相对路径

相对路径：在编译时是指一个文件或目录相对于另一个文件或目录的位置，在运行时是指一个文件相对于当前页面路由的位置（不建议使用运行时的相对路径，应该优先使用绝对路径）。

例如：

HTML

<template>
  <!-- 绑定动态路径 -->
  <image :src="src" />
</template>
<script setup>
// 编译时：使用 import 语句相对路径导入图片
import logo from "../../static/logo.png";
console.log(logo); // import 语句会在编译阶段根据当前文件位置转换为绝对路径

// 运行时
// 错误的相对路径用法，image 组件会在运行时根据当前页面路由来转换该相对路径，当不同的页面使用 custom 组件时，转换的路径是不同的
// 应该使用绝对路径：/static/logo.png，这样可以确保在任意页面都访问到正确的图片地址
const src = "../../static/logo.png";

uni.navigateTo({
  // 运行时
  // 错误的相对路径用法，路由会在运行时根据当前页面路由来转换该相对路径
  // 应该使用绝对路径：/pages/index/index
  url: "../../pages/index/index",
});
</script>

注意：

在 uni-app x 项目中，dialogPage 不影响页面栈和路由地址，所以也不会影响运行时的相对路径转换。

2. 引用组件

传统 vue 项目开发，引用组件需要 “导入 -> 注册 -> 使用” 三个步骤，如下：

HTML

<template>
  <view>
    <!-- 3. 使用组件 -->
    <uni-rate text="1"></uni-rate>
  </view>
</template>
<script>
// 1. 导入组件
import uniRate from "@/components/uni-rate/uni-rate.vue";
export default {
  components: { uniRate }, // 2. 注册组件
};
</script>

Vue 3.x 增加了 script setup 特性，将三步优化为两步，无需注册步骤，更为简洁：

HTML

<template>
  <view>
    <!-- 2. 使用组件 -->
    <uni-rate text="1"></uni-rate>
  </view>
</template>
<script setup>
// 1. 导入组件
import uniRate from "@/components/uni-rate/uni-rate.vue";
</script>

uni-app 的 easycom 机制，将组件引用进一步优化，开发者只管使用，无需考虑导入和注册，更为高效：

HTML

<template>
  <view>
    <!-- 1. 使用组件 -->
    <uni-rate text="1"></uni-rate>
  </view>
</template>
<script></script>

在 uni-app 项目中，页面引用组件和组件引用组件的方式都是一样的（可以理解为：页面是一种特殊的组件），均支持通过 easycom 方式直接引用。

easycom 规范详细介绍，参考：easycom。

3. 引用 js

3.1. js 文件引入

js 文件或 script 标签内（包括 renderjs 等）引入 js 文件时，可以使用相对路径和绝对路径，形式如下：

JavaScript

// 绝对路径，@指向项目根目录，在 cli 项目中 @ 指向 src 目录
import add from "@/common/add.js";
// 相对路径
import add from "../../common/add.js";

警告

js 文件不支持使用 / 开头的方式引入。

3.2. NPM 支持

uni-app 支持使用 npm 安装第三方包。

此文档要求开发者们对 npm 有一定的了解，因此不会再去介绍 npm 的基本功能。如若之前未接触过 npm，请翻阅 NPM 官方文档进行学习。

初始化 npm 工程
若项目之前未使用 npm 管理依赖（项目根目录下无 package.json 文件），先在项目根目录执行命令初始化 npm 工程：
PowerShell
```
npm init -y
```
cli 项目默认已经有 package.json 了。HBuilderX 创建的项目默认没有，需要通过初始化命令来创建。
安装依赖
在项目根目录执行命令安装 npm 包：
PowerShell
```
npm install packageName --save
```

使用

安装完即可使用 npm 包，js 中引入 npm 包：

JavaScript

import package from "packageName";
const package = require("packageName");

注意：

为多端兼容考虑，建议优先从 uni-app 插件市场获取插件。直接从 npm 下载库很容易只兼容 H5 端。
非 H5 端不支持使用含有 dom、window 等操作的 vue 组件和 js 模块，安装的模块及其依赖的模块使用的 API 必须是 uni-app 已有的 API（兼容小程序 API），比如：支持高德地图微信小程序 SDK。类似 jQuery 等库只能用于 H5 端。
node_modules 目录必须在项目根目录下。不管是 cli 项目还是 HBuilderX 创建的项目。
关于 ui 库的获取，详见多端 UI 库。

4. 引用 css

使用 @import 语句可以导入外联样式表，@import 后跟需要导入的外联样式表的相对路径，用 ; 表示语句结束。

示例代码：

HTML

<style>
  @import "../../common/uni.css";

  .uni-card {
    box-shadow: none;
  }
</style>

5. 引用 json

uni-app vue3 和 uni-app x (HBuilderX 4.25+) 项目支持引入 json 文件。

js、ts、uts 文件或 script 标签内引入 json 文件时，可以使用相对路径或绝对路径，例如:

JavaScript

// 绝对路径，@ 指向项目根目录，在 cli 项目中 @ 指向 src 目录
import pagesJson from "@/pages.json";
// 相对路径
import pagesJson from "../../common/pages.json";

导入 json 文件时支持解构，此时会根据导入内容进行摇树，减小包体积，例如：

JavaScript

import { pages } from "@/pages.json";

导入的 json 文件内部支持条件编译，导入的结果是根据条件编译规则进行处理后的结果，以如下 json 文件为例：

JSON

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "index"
      }
    },
    // #ifdef APP
    {
      "path": "pages/index/app",
      "style": {
        "navigationBarTitleText": "app"
      }
    },
    // #endif
    // #ifdef H5
    {
      "path": "pages/index/web",
      "style": {
        "navigationBarTitleText": "web"
      }
    }
    // #endif
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  },
  "uniIdRouter": {}
}

在 App 平台导入的结果中，pages 下只包含 path 为 pages/index/index 和 pages/index/app 的对象。

在 Web 平台导入的结果中，pages 下只包含 path 为 pages/index/index 和 pages/index/web 的对象。

6. 引用静态资源

6.1. 模板内引入静态资源

template 内引入静态资源，如 image、video 等标签的 src 属性时，可以使用相对路径或者绝对路径，形式如下：

HTML

<!-- 绝对路径，/static 指根目录下的 static 目录，在 cli 项目中 /static 指 src 目录下的 static 目录 -->
<image class="logo" src="/static/logo.png"></image>
<image class="logo" src="@/static/logo.png"></image>
<!-- 相对路径 -->
<image class="logo" src="../../static/logo.png"></image>

注意：

@ 开头的绝对路径以及相对路径会经过 base64 转换规则校验：
- 引入的静态资源在非 web 平台，均不转为 base64；
- web 平台，小于 4kb 的资源会被转换成 base64，其余不转；
自 HBuilderX 2.6.6 起 template 内支持 @ 开头路径引入静态资源，旧版本不支持此方式。
App 平台自 HBuilderX 2.6.9 起 template 节点中引用静态资源文件时（如：图片），调整查找策略为 “基于当前文件的路径搜索”，与其他平台保持一致。
支付宝小程序组件内 image 标签不可使用相对路径。

6.2. css 引入静态资源

css 文件或 style 标签内引入 css 文件时（scss、less 文件同理），可以使用相对路径或绝对路径（HBuilderX 2.6.6）。

JavaScript

/* 绝对路径 */
@import url('/common/uni.css');
@import url('@/common/uni.css');
/* 相对路径 */
@import url('../../common/uni.css');

信息

自 HBuilderX 2.6.6 起支持绝对路径引入静态资源，旧版本不支持此方式。

css 文件或 style 标签内引用的图片路径可以使用相对路径也可以使用绝对路径，需要注意的是，有些小程序端 css 文件不允许引用本地文件（请看注意事项）。

CSS

/* 绝对路径 */
background-image: url(/static/logo.png);
background-image: url(@/static/logo.png);
/* 相对路径 */
background-image: url(../../static/logo.png);

Tips

引入字体图标请参考，字体图标。
@ 开头的绝对路径以及相对路径会经过 base64 转换规则校验。
不支持本地图片的平台，小于 40kb，一定会转 base64。（共四个平台 mp-weixin, mp-qq, mp-toutiao, app v2）
web 平台，小于 4kb 会转 base64，超出 4kb 时不转。
其余平台不会转 base64。

6.3. js/uts 引入静态资源

js/uts 中引入静态资源，多用于静态资源存放在非 static 目录中的情况，可以使用 import 引入相对路径或绝对路径。

例如，有如下目录结构，在 static 和页面文件夹下分别有静态资源：

Text

├── pages
│   └── index
│       │── index.uvue
│       └── icon.png
└── static
    └── logo.png

正常情况下，如 image 的 src 中直接引入 static 中 logo.png，可以使用相对路径或绝对路径：

HTML

<!-- /pages/index/index.vue -->
<template>
  <view class="content">
    <image src="../../static/logo.png" />
    <image src="/static/logo.png" />
    <image src="@static/logo.png" />
  </view>
</template>

而引入 index 下的 icon.png 不管是相对还是绝对路径，都无法显示，所以这时候需要在 js/uts 中使用 import 来引入：

HTML

<!-- /pages/index/index.vue -->
<template>
  <view class="content">
    <image :src="src" />
  </view>
</template>

<script>
// 使用 import 引入静态资源，并在 data 中赋值引用
import icon_src from "./icon.png";
export default {
  data() {
    return {
      src: icon_src,
    };
  },
};
</script>

6.4. 静态资源引入注意事项

通常项目中规定根目录下的 static 为静态资源文件夹（目前暂不支持修改），资源存放此处后，可在任意文件直接使用相对或者绝对路径引用，具体参考上述模板 css/js/uts 中引入静态资源的说明。

而非 static 目录的静态资源，不支持直接引用，需要在 js/uts 中使用 import 来引入，确保路径正确。

综上所述，我们总结一下静态资源引用的注意事项：

在模板或者 css 文件使用 static 目录中的静态资源，无需特殊处理，可直接通过相对路径或者绝对路径直接引入。
在 js/uts 文件使用静态资源，需要使用 import 来引入。
不管在任何文件引入非 static 目中的静态资源，均需在 js/uts 文件使用 import 来引入。

6.5. 静态资源编译规则

项目 static 目录下的静态资源，会被直接拷贝到编译后目录的 static 目录下。

非 static 目录下的静态资源在 vue3 下，被引用的资源会编译到 assets 目录下，并重新命名为原始名称 + 内容 hash, 如：logo.png 会编译为类似 logo.cfd8fa94.png 的名称。如果该静态资源未被引用，则不会被编译器处理。

非 static 目录下的静态资源在 vue2 不同平台下，编译规则有些不同：

web: 静态资源将会编译到 static -> img 下，如小于 4k 则转为 base64；
小程序：静态资源将会编译到资源同名文件下，如小于 40kb 则转 base64；
app: 静态资源将会编译到资源同名文件下；

信息

自 HBuilderX 4.0 起 vue2 已和 vue3 保持一致。

7. 引用原生插件

uni-app 在 App 侧的原生扩展插件，支持使用 java、object-c 等原生语言编写。

从 HBuilderX 3.6 起，新增支持了使用 uts 来开发原生插件。文档另见 uts 插件。

为了和 uts 插件区别，之前的 App 原生插件，改名为 App 原生语言插件。

本文为 App 原生语言插件的开发文档。

7.1. `uni.requireNativePlugin(PluginName)`

引入 App 原生语言插件。

平台差异说明：App。

自 HBuilderX 1.4 版本起，uni-app 支持引入原生插件，使用方式如下：

JavaScript

const PluginName = uni.requireNativePlugin(PluginName); // PluginName 为原生插件名称

不管是 vue 文件还是 nvue 文件，都是这个 API。

7.2. 内置原生插件

内置原生插件，uni-app 已默认集成，支持直接在内置基座运行。

仅在 nvue 页面，支持引入 BindingX、animation、DOM.addRule 等。

在 vue 页面，支持引入 clipboard、storage、stream、deviceInfo 等。

使用方式：可通过 uni.requireNativePlugin 直接使用。

示例：

HTML

<template>
  <view>
    <text class="my-iconfont">&#xe85c;</text>
  </view>
</template>
<script>
export default {
  beforeCreate() {
    const domModule = uni.requireNativePlugin("dom");
    domModule.addRule("fontFace", {
      fontFamily: "myIconfont",
      src: "url('http://at.alicdn.com/t/font_2234252_v3hj1klw6k9.ttf')",
    });
  },
};
</script>
<style>
.my-iconfont {
  font-family: myIconfont;
  font-size: 60rpx;
  color: #00aaff;
}
</style>

非内置原生插件，分为本地插件和云端插件。集成原生插件后，需要提交云端打包或制作自定义基座运行才会生效。

7.3. 本地插件（非内置原生插件）

本地插件，是 uni-app 项目 nativeplugins 目录（目录不存在则创建）下的原生插件。

第一步：获取本地原生插件
1. 方式一：插件市场下载免费 uni-app 原生插件
  可以登录 uni 原生插件市场，在免费的插件详情页中点击 “下载 for 离线打包” 下载原生插件（zip 格式），解压到 HBuilderX 的 uni-app 项目下的 nativeplugins 目录（如不存在则创建），以下是 DCloud-RichAlert 插件举例，它的下载地址是：https://ext.dcloud.net.cn/plugin?id=36。
  下载解压后目录结构如下：
  图 7.1 - 解压后的目录结构
2. 方式二：开发者自己开发 uni-app 原生插件
  原生插件开发完成后按指定格式压缩为 zip 包，参考 uni-app 原生插件格式说明文档。按上图的格式配置到 uni-app 项目下的 nativeplugins 目录。
第二步：配置本地原生插件
在 manifest.json -> App 原生插件配置 -> 选择本地插件 -> 选择需要打包生效的插件 -> 保存后提交云端打包生效。
图 7.2 - 配置本地原生插件
第三步：开发调试本地原生插件
在 vue 页面或 nvue 页面引入这个原生插件。
使用 uni.requireNativePlugin 的 api，参数为插件的 id。
JavaScript
```
const dcRichAlert = uni.requireNativePlugin("DCloud-RichAlert");
```
第四步：打包发布
使用自定义基座开发调试本地原生插件后，不可直接将自定义基座 apk 作为正式版发布。应该重新提交云端打包（不能勾选 “自定义基座”）生成正式版本。

7.4. 云端插件（非内置原生插件）

云端插件，已经在插件市场绑定或购买的插件，无需下载插件到工程中，云打包时会直接合并打包原生插件到 APP 中。（试用插件只能在自定义基座中使用）

第一步：购买或下载 uni-app 原生插件
使用前需先登录 uni 原生插件市场，在插件详情页中购买，免费插件也可以在插件市场 0 元购。购买后才能够云端打包使用插件。
购买插件时请选择正确的 appid，以及绑定正确包名。
第二步：使用自定义基座打包 uni 原生插件（注：请使用真机运行自定义基座）
在 manifest.json -> App 原生插件配置 -> 选择云端插件 -> 选择需要打包的插件 -> 保存后提交云端打包生效。
图 7.3 - 打包 uni 原生插件

第三步：开发调试 uni-app 原生插件

在 vue 页面或 nvue 页面引入这个原生插件。

使用 uni.requireNativePlugin 的 api，参数为插件的 id。

在页面引入原生插件，uni.requireNativePlugin 使用后返回一个对象：
JavaScript
```
const dcRichAlert = uni.requireNativePlugin("DCloud-RichAlert");
```

使用原生插件

JavaScript

dcRichAlert.show(
  {
    position: "bottom",
    title: "提示信息",
    titleColor: "#FF0000",
    content: "<a href='https://uniapp.dcloud.io/' value='Hello uni-app'>uni-app</a> 是一个使用 Vue.js 开发跨平台应用的前端框架!\n 免费的\n 免费的\n 免费的\n 重要的事情说三遍",
    contentAlign: "left",
    checkBox: {
      title: "不再提示",
      isSelected: true,
    },
    buttons: [
      {
        title: "取消",
      },
      {
        title: "否",
      },
      {
        title: "确认",
        titleColor: "#3F51B5",
      },
    ],
  },
  (result) => {
    console.log(result);
  }
);

第四步：打包发布
使用自定义基座开发调试 uni-app 原生插件后，不可直接将自定义基座 apk 作为正式版发布。应该重新提交云端打包（不能勾选 “自定义基座”）生成正式版本。

7.5. 注意事项

可以在插件市场查看更多插件，如需开发 uni 原生插件请参考 uni 原生插件开发文档。
如果插件需要传递文件路径，则需要传手机文件的绝对路径，可使用 5+ IO 模块的相关 API 得到文件的绝对路径。

UniApp 互相引用 ​

1. 绝对路径和相对路径 ​

1.1. 绝对路径 ​

1.2. 相对路径 ​

2. 引用组件 ​

3. 引用 js ​

3.1. js 文件引入 ​

3.2. NPM 支持 ​

4. 引用 css ​

5. 引用 json ​

6. 引用静态资源 ​

6.1. 模板内引入静态资源 ​

6.2. css 引入静态资源 ​

6.3. js/uts 引入静态资源 ​

6.4. 静态资源引入注意事项 ​

6.5. 静态资源编译规则 ​

7. 引用原生插件 ​

7.1. uni.requireNativePlugin(PluginName) ​

7.2. 内置原生插件 ​

7.3. 本地插件（非内置原生插件） ​

7.4. 云端插件（非内置原生插件） ​

7.5. 注意事项 ​

UniApp 互相引用

1. 绝对路径和相对路径

1.1. 绝对路径

1.2. 相对路径

2. 引用组件

3. 引用 js

3.1. js 文件引入

3.2. NPM 支持

4. 引用 css

5. 引用 json

6. 引用静态资源

6.1. 模板内引入静态资源

6.2. css 引入静态资源

6.3. js/uts 引入静态资源

6.4. 静态资源引入注意事项

6.5. 静态资源编译规则

7. 引用原生插件

7.1. `uni.requireNativePlugin(PluginName)`

7.2. 内置原生插件

7.3. 本地插件（非内置原生插件）

7.4. 云端插件（非内置原生插件）

7.5. 注意事项