博主：_LJaXi Or 東方幻想郷
专栏： uni-app | 小程序开发
开发工具：HBuilderX

引用组件

传统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 方式直接引用。

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

easycom

HBuilderX 2.5.5 起支持 easycom 组件模式

传统 vue 组件，需要安装、引用、注册，三个步骤后才能使用组件

easycom将其精简为一步。 只要组件安装在项目根目录或uni_modules的components目录下，并符合components/组件名称/组件名称.vue或uni_modules/插件ID/components/组件名称/组件名称.vue目录结构，就可以不用引用、注册，直接在页面中使用

<template><view class="container"><uni-list><uni-list-item title="第一行"></uni-list-item><uni-list-item title="第二行"></uni-list-item></uni-list></view>
</template>
<script>// 这里不用import引入，也不需要在components内注册uni-list组件。template里就可以直接用export default {data() {return {}}}
</script>

不管components目录下安装了多少组件，easycom打包后会自动剔除没有使用的组件，对组件库的使用尤为友好。

组件库批量安装，随意使用，自动按需打包。以官方的uni-ui为例，在HBuilderX新建项目界面选择uni-ui项目模板，只需在页面中敲u，拉出大量组件代码块，直接选择，即可使用。大幅提升开发效率，降低使用门槛。

在uni-app插件市场下载符合components/组件名称/组件名称.vue目录结构的组件，均可直接使用。

easycom是自动开启的，不需要手动开启，有需求时可以在pages.json的easycom节点进行个性化设置，如关闭自动扫描，或自定义扫描匹配组件的策略。设置参数如下：

属性	类型	默认值	描述
autoscan	Boolean	true	是否开启自动扫描，开启后将会自动扫描符合components/组件名称/组件名称.vue目录结构的组件
custom	Object	-	以正则方式自定义组件匹配规则。如果autoscan不能满足需求，可以使用custom自定义匹配规则

自定义easycom配置的示例

如果需要匹配 node_modules 内的 vue 文件，需要使用packageName/path/to/vue-file-$1.vue形式的匹配规则，其中packageName为安装的包名，/path/to/vue-file-$1.vue为 vue 文件在包内的路径。

"easycom": {"autoscan": true,"custom": {"^uni-(.*)": "@/components/uni-$1.vue", // 匹配components目录内的vue文件"^vue-file-(.*)": "packageName/path/to/vue-file-$1.vue" // 匹配node_modules内的vue文件}
}

说明

• easycom方式引入的组件无需在页面内import，也不需要在components内声明，即可在任意页面使用
• easycom方式引入组件不是全局引入，而是局部引入。例如在H5端只有加载相应页面才会加载使用的组件
• 在组件名完全一致的情况下，easycom引入的优先级低于手动引入（区分连字符形式与驼峰形式）
• 考虑到编译速度，直接在pages.json内修改easycom不会触发重新编译，需要改动页面内容触发。
• easycom只处理vue组件，不处理小程序专用组件（如微信的wxml格式组件）。不处理后缀为.nvue的组件。但vue组件也可以全端运行，包括小程序和app-nvue。可以参考uni ui，使用vue后缀，同时兼容nvue页面。
• nvue页面里引用.vue后缀的组件，会按照nvue方式使用原生渲染，其中不支持的css会被忽略掉。这种情况同样支持easycom

Js文件引入

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

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

注意

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

NPM支持

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

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

初始化npm工程

若项目之前未使用npm管理依赖（项目根目录下无package.json文件），先在项目根目录执行命令初始化npm工程：

npm init -y

cli项目默认已经有package.json了。HBuilderX创建的项目默认没有，需要通过初始化命令来创建。

安装依赖

在项目根目录执行命令安装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 目录必须在项目根目录下。不管是cli项目还是HBuilderX创建的项目。
• 关于ui库的获取，详见多端UI库

Css文件引入

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

示例代码：

<style>@import "../../common/uni.css";.uni-card {box-shadow: none;}
</style>

静态资源引入

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

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

Tips

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

如何引入字体图标？

uni-app 支持使用字体图标，使用方式与普通 web 项目相同，需要注意以下几点

• 支持 base64 格式字体图标。
• 支持网络路径字体图标。
• 小程序不支持在 css 中使用本地文件，包括本地的背景图和字体文件。需以 base64 方式方可使用。
• 网络路径必须加协议头 https。
• 从 http://www.iconfont.cn 上拷贝的代码，默认是没加协议头的。
• 从 http://www.iconfont.cn 上下载的字体文件，都是同名字体（字体名都叫 iconfont，安装字体文件时可以看到），在 nvue 内使用时需要注意，此字体名重复可能会显示不正常，可以使用工具修改。
• 使用本地路径图标字体需注意：
  1. 为方便开发者，在字体文件小于 40kb 时，uni-app 会自动将其转化为 base64 格式；
  2. 字体文件大于等于 40kb，仍转换为 base64 方式使用的话可能有性能问题，如开发者必须使用，则需自己将其转换为 base64 格式使用，或将其挪到服务器上，从网络地址引用；
  3. 字体文件的引用路径推荐使用以 ~@ 开头的绝对路径

@font-face {font-family: test1-icon;src: url('~@/static/iconfont.ttf');
}

css 引入字体图标示例

<template><view><view><text class="test">&#xe600;</text><text class="test">&#xe687;</text><text class="test">&#xe60b;</text></view></view>
</template>
<style>
@font-face {font-family: 'iconfont';src: url('https://at.alicdn.com/t/font_865816_17gjspmmrkti.ttf') format('truetype');
}
.test {font-family: iconfont;margin-left: 20rpx;
}
</style>

nvue 引入字体图标注意事项

nvue中不可直接使用 css 的方式引入字体文件，需要使用以下方式在 js 内引入。nvue 内不支持本地路径引入字体，请使用网络链接或者base64形式。src字段的url的括号内一定要使用单引号

var domModule = weex.requireModule('dom');
domModule.addRule('fontFace', {fontFamily: 'fontFamilyName',src: "url('https://...')",
});

Vue2 语法简介绍

引入js文件 以及 高级用法

以前通过script src、link href引入外部的js和css

<script src="js/jquery-1.10.2.js" type="text/javascript"></script>  
<link href="css/bootstrap.css" rel="stylesheet" type="text/css"/>

现在使用 Es6 语法的 import 引入外部的 js模块或css，只要 require 进来，就会变为对象

在hello uni-app的 common 目录有一个工具类 util.js ，可以在hello uni-app中搜索这个例子查看。hello uni-app示例代码可从 github 获取

<script>  var util = require('../../../common/util.js');  //require这个js模块  var formatedPlayTime = util.formatTime(playTime); //调用js模块的方法  
</script>

function formatTime(time) {  return time;//这里没写逻辑  
}  
module.exports = {  formatTime: formatTime  
}

高级写法

// 直接使用js模块的属性。在hello uni-app有示例 
var dateUtils = require('../../../common/util.js').dateUtils; 
// 将js导入并重命名为echarts，然后使用echarts.来继续执行方法。在hello uni-app有示例 
import * as echarts from '/components/echarts/echarts.simple.min.js'; 

App.vue 全局样式

css外部文件导入全局样式，在根目录下的 app.vue 里写入，每个页面都会加载 app.vue 里的样式

<style>  @import "./common/uni.css";  .uni-hello-text{  color:#7A7E83;  }  
</style>

组件

按照 Vue 单文件组件规范，在 uni-app 下如下格式表示

<template><view><view>{{userName}}</view></view>
</template>
<script>export default {data() {return {"userName":"foo"}}}
</script>

全局注册

uni-app 支持配置全局组件，需在 main.js 里进行全局注册，注册后就可在所有页面里使用该组件

1. main.js 里进行全局导入和注册

import Vue from 'vue'
import pageHead from './components/page-head.vue'
Vue.component('page-head',pageHead)

2. index.vue 里可直接使用组件

<template><view><page-head></page-head></view>
</template>

组件互传

可参考 Vue 组件互传

Vue2 项目转 Vue3 项目

参考：Vue2 转 Vue3

ts/TypeScript支持

uni-app 支持使用 ts 开发

基本用法

• HBuilderX创建的项目

在 vue 页面的 script 节点，添加属性 lang="ts"

<script lang="ts">
// 这里编写ts代码let s:string = "123"console.log(s)
</script>

• cli创建的项目

需要在创建项目时就指定ts，具体请另行参考文档

修改 Typescript 配置

在根目录创建 tsconfig.json 文件，并进行个性化配置，推荐配置如下

// tsconfig.json
{"compilerOptions": {"target": "esnext","module": "esnext","strict": true,"jsx": "preserve","moduleResolution": "node","esModuleInterop": true,"sourceMap": true,"skipLibCheck": true,"importHelpers": true,"allowSyntheticDefaultImports": true,"useDefineForClassFields": true,"resolveJsonModule": true,"lib": ["esnext","dom"],"types": ["@dcloudio/types"]},"exclude": ["node_modules","unpackage","src/**/*.nvue"]
}

个性化配置是可选的，没有tsconfig.json时会自动使用默认配置运行

ts组件问题

当指定 lang="ts" 后，该 vue 文件引入的所有组件都必须使用 ts 语言进行编写

示例代码

改造 uni-badge.vue

<script lang="ts">// 仅展示需要修改的核心代码，完整代码请参考原来的组件。import Vue from 'vue';export default Vue.extend({props: {type: {type: String,default: 'default'},inverted: {type: Boolean,default: false},text: {type: [String, Number],default: ''},size: {type: String,default: 'normal'}},computed: {setClass(): string {const classList: string[] = ['uni-badge-' + this.type, 'uni-badge-size-' + this.size];if (this.inverted === true) {classList.push('uni-badge-inverted')}return classList.join(" ")}},methods: {onClick() {this.$emit('click')}}})
</script>

在 index.vue 中引用 uni-badge 组件

<script lang="ts">import Vue from 'vue';import uniBadge from '../../components/uni-badge.vue';export default Vue.extend({data() {return {title: 'Hello'}},components:{uniBadge}});
</script>

JSX/TSX 支持

安装插件

npm install @vitejs/plugin-vue-jsx --save-dev

配置 vite.config.js

项目根目录新增 vite.config.js 文件，并增加如下配置

import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import vueJsx from '@vitejs/plugin-vue-jsx'export default defineConfig({plugins: [uni(),vueJsx({// options are passed on to @vue/babel-plugin-jsx})],
});

• cli创建的项目

项目根目录 vite.config.js 文件中增加如下配置

import vueJsx from '@vitejs/plugin-vue-jsx'export default defineConfig({plugins: [vueJsx({// options are passed on to @vue/babel-plugin-jsx}),],
}

UTS 语言

可前往此页面进行 uts 系统学习: uts 语言