引用组件
传统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 内使用时需要注意,此字体名重复可能会显示不正常,可以使用工具修改。
- 使用本地路径图标字体需注意:
- 为方便开发者,在字体文件小于 40kb 时,
uni-app
会自动将其转化为 base64 格式; - 字体文件大于等于 40kb,仍转换为 base64 方式使用的话可能有性能问题,如开发者必须使用,则需自己将其转换为 base64 格式使用,或将其挪到服务器上,从网络地址引用;
- 字体文件的引用路径推荐使用以 ~@ 开头的绝对路径
@font-face { font-family: test1-icon; src: url('~@/static/iconfont.ttf'); }
css 引入字体图标示例
<template> <view> <view> <text class="test"></text> <text class="test"></text> <text class="test"></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
里进行全局注册,注册后就可在所有页面里使用该组件
main.js
里进行全局导入和注册
import Vue from 'vue' import pageHead from './components/page-head.vue' Vue.component('page-head',pageHead)
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 语言