当前位置：首页 > news >正文

uni-app（3）：互相引用

news 来源：原创 2025/5/23 5:24:09

1 绝对路径和相对路径

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

1.1 绝对路径

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

<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 相对路径

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

<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/indexurl: "../../pages/index/index",
});
</script>

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

2 引用组件

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

<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特性，将三步优化为两步，无需注册步骤，更为简洁：

<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机制，将组件引用进一步优化，开发者只管使用，无需考虑导入和注册，更为高效：

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

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

3 引用js

3.1 js 文件引入

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

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

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

3.2 NPM支持

uni-app支持使用npm安装第三方包。此文档要求开发者们对npm有一定的了解，因此不会再去介绍npm的基本功能。若项目之前未使用npm管理依赖（项目根目录下无package.json文件），先在项目根目录执行命令初始化npm工程：

npm init -y

在项目根目录执行命令安装npm包：

npm install packageName --save

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

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 目录必须在项目根目录下。

4 应用css

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

<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 文件时，可以使用相对路径或绝对路径，例如:

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

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

import { pages } from '@/pages.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属性时，可以使用相对路径或者绝对路径，形式如下

<!-- 绝对路径，/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）

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

自HBuilderX 2.6.6起支持绝对路径引入静态资源，旧版本不支持此方式。css文件或style标签内引用的图片路径可以使用相对路径也可以使用绝对路径，需要注意的是，有些小程序端 css 文件不允许引用本地文件。

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

@开头的绝对路径以及相对路径会经过 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 和页面文件夹下分别有静态资源

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

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

<!-- /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 来引入

<!-- /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不同平台下，编译规则有些不同（自 HBuilderX 4.0 起已和 vue3 保持一致）：

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

7 引用原生插件

uni-app在App侧的原生扩展插件，支持使用java、object-c等原生语言编写。从HBuilderX 3.6起，新增支持了使用uts来开发原生插件。为了和uts插件区别，之前的App原生插件，改名为App原生语言插件。

7.1 uni.requireNativePlugin(PluginName)

引入 App 原生语言插件。平台差异说明：App。自 HBuilderX 1.4 版本起，uni-app 支持引入原生插件，使用方式如下：

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直接使用。

<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>