应用配置 | uni-app官网

应用配置

应用 API

全局 API

展示全部

# 应用配置

config 是一个包含了 Vue 应用全局配置的对象。你可以在应用挂载前修改其以下 property：

const app = Vue.createApp({})

app.config = {...}

应用配置	描述	H5	App端	微信小程序	说明
errorHandler	指定一个处理函数，来处理组件渲染方法执行期间以及侦听器抛出的未捕获错误。详情	√	√	√
warnHandler	为 `Vue` 的运行时警告指定一个自定义处理函数。详情	√	√	√
globalProperties	添加可以在应用程序内的任何组件实例中访问的全局 `property`。详情	√	√	√
isCustomElement	指定一个方法，用来识别在 `Vue` 之外定义的自定义元素。详情	√	√	√
optionMergeStrategies	为自定义选项定义合并策略。详情	√	√	√
performance	设置为 `true` 以在浏览器开发工具的 `performance/timeline` 面板中启用对组件初始化、编译、渲染和更新的性能追踪。详情	√	x	x	只在Web环境下支持

# 应用 API

在 Vue 3 中，改变全局 Vue 行为的 API 现在被移动到了由新的 createApp 方法所创建的应用实例上。此外，现在它们的影响仅限于该特定应用实例：

import { createApp } from 'vue'

const app = createApp({})

调用 createApp 返回一个应用实例。该实例提供了一个应用上下文。应用实例挂载的整个组件树共享相同的上下文，该上下文提供了之前在 Vue 2.x 中“全局”的配置。

另外，由于 createApp 方法返回应用实例本身，因此可以在其后链式调用其它方法，这些方法可以在以下部分中找到。

应用 API	描述	H5	App端	微信小程序	说明
component	注册或检索全局组件。详情	√	√	√
config	包含应用配置的对象。详情	√	√	√
directive	注册或检索全局指令。详情	√	√	x
mixin	在整个应用范围内应用混入。详情	√	√	√	nvue 页面暂不支持
provide	设置一个可以被注入到应用范围内所有组件中的值。详情	√	√	√
use	安装 `Vue.js` 插件。详情	√	√	√

# 全局 API

全局 API	描述	H5	App端	微信小程序
createApp	返回一个提供应用上下文的应用实例。应用实例挂载的整个组件树共享同一个上下文。详情	√	√	√
h	返回一个”虚拟节点“，通常缩写为 `VNode`：一个普通对象，其中包含向 `Vue` 描述它应在页面上渲染哪种节点的信息，包括所有子节点的描述。详情	√	x	x
defineComponent	从实现上看，`defineComponent` 只返回传递给它的对象。但是，就类型而言，返回的值有一个合成类型的构造函数，用于手动渲染函数、`TSX` 和 `IDE` 工具支持。详情	√	x	x
defineAsyncComponent	创建一个只有在需要时才会加载的异步组件。详情	√	x	x
resolveComponent	如果在当前应用实例中可用，则允许按名称解析 `component`。返回一个 `Component`。详情	√	x	x
resolveDynamicComponent	允许使用与 `component :is=""` 相同的机制来解析一个 `component`。详情	√	x	x
resolveDirective	如果在当前应用实例中可用，则允许通过其名称解析一个 `directive`。返回一个 `Directive`。详情	√	x	x
withDirectives	允许将指令应用于 `VNode`。返回一个包含应用指令的 `VNode`。详情	√	x	x
createRenderer	createRenderer 函数接受两个泛型参数： `HostNode` 和 `HostElement`，对应于宿主环境中的 `Node` 和 `Element` 类型。详情	√	x	x
nextTick	将回调推迟到下一个 `DOM` 更新周期之后执行。在更改了一些数据以等待 `DOM` 更新后立即使用它。详情	√	x	x

# 选项/Data

Data	描述	H5	App端	微信小程序
data	返回组件实例的 `data` 对象的函数。详情	√	√	√
props	`props` 可以是数组或对象，用于接收来自父组件的数据。详情	√	√	√
computed	计算属性将被混入到组件实例中。所有 `getter` 和 `setter` 的 `this` 上下文自动地绑定为组件实例。详情	√	√	√
methods	methods 将被混入到组件实例中。可以直接通过 `VM` 实例访问这些方法，或者在指令表达式中使用。方法中的 `this` 自动绑定为组件实例。详情	√	√	√
watch	一个对象，键是需要观察的表达式，值是对应回调函数。值也可以是方法名，或者包含选项的对象。详情	√	√	√
emits	emits 可以是数组或对象，从组件触发自定义事件，`emits` 可以是简单的数组，或者对象作为替代，允许配置和事件验证。详情	√	√	√

# 选项/DOM

DOM	描述	H5	App端	微信小程序	说明
template	一个字符串模板作为 `component` 实例的标识使用。详情	√	x	x	uni-app使用的vue是只包含运行时的版本
render	字符串模板的另一种选择，允许你充分利用 `JavaScript` 的编程功能。详情	√	x	x	-

# 选项/生命周期钩子

生命周期钩子	描述	H5	App端	微信小程序
beforeCreate	在实例初始化之后，数据观测`(data observer)`和 `event/watcher` 事件配置之前被调用。详情	√	√	√
created	在实例创建完成后被立即调用。详情	√	√	√
beforeMount	在挂载开始之前被调用：相关的 `render` 函数首次被调用。详情	√	√	√
mounted	实例被挂载后调用，这时 `Vue.createApp({}).mount()` 被新创建的 `vm.$el` 替换了。详情	√	√	√
beforeUpdate	数据更新时调用，发生在虚拟 `DOM` 打补丁之前。详情	√	√	√
updated	由于数据更改导致的虚拟 `DOM` 重新渲染和打补丁，在这之后会调用该钩子。详情	√	√	√
activated	被 `keep-alive` 缓存的组件激活时调用。详情	√	√	x
deactivated	被 `keep-alive` 缓存的组件停用时调用。详情	√	√	x
beforeUnmount	在卸载组件实例之前调用。在这个阶段，实例仍然是完全正常的。详情	√	√	√
unmounted	卸载组件实例后调用。调用此钩子时，组件实例的所有指令都被解除绑定，所有事件侦听器都被移除，所有子组件实例被卸载。详情	√	√	√
errorCaptured	当捕获一个来自子孙组件的错误时被调用。此钩子会收到三个参数：错误对象、发生错误的组件实例以及一个包含错误来源信息的字符串。详情	√	√	√
renderTracked	跟踪虚拟 `DOM` 重新渲染时调用。钩子接收 `debugger event` 作为参数。此事件告诉你哪个操作跟踪了组件以及该操作的目标对象和键。详情	√	√	√
renderTriggered	当虚拟 `DOM` 重新渲染为 `triggered.Similarly` 为`renderTracked`，接收 `debugger event` 作为参数。此事件告诉你是什么操作触发了重新渲染，以及该操作的目标对象和键。详情	√	√	√

页面及组件生命周期流程图

# 选项/资源

资源	描述	H5	App端	微信小程序
directives	包含组件实例可用指令的哈希表。详情	√	√	x
components	包含组件实例可用组件的哈希表。详情	√	√	√

# 选项/组合

组合	描述	H5	App端	微信小程序
mixins	接收一个混入对象的数组。这些混入对象可以像正常的实例对象一样包含实例选项，这些选项将会被合并到最终的选项中，使用特定的选项合并逻辑。详情	√	√	√
extends	允许声明扩展另一个组件 (可以是一个简单的选项对象或构造函数)。这主要是为了便于扩展单文件组件。详情	√	√	√
provide / inject	这对选项需要一起使用，以允许一个祖先组件向其所有子孙后代注入一个依赖，不论组件层次有多深，并在起上下游关系成立的时间里始终生效。详情	√	√	√
setup	`setup` 函数是一个新的组件选项。它作为在组件内部使用组合式 `API` 的入口点。详情	√	√	√

# 选项/杂项

杂项	描述	H5	App端	微信小程序
name	允许组件模板递归地调用自身。注意，组件在全局用 `Vue.createApp({}).component({})` 注册时，全局 `ID` 自动作为组件的 `name`。详情	√	√	√
delimiters	设置用于模板内文本插入的分隔符。详情	√	x	x
inheritAttrs	默认情况下父作用域的不被认作 `props` 的 `attribute` 绑定 (`attribute bindings`) 将会“回退”且作为普通的 `HTML attribute` 应用在子组件的根元素上。当撰写包裹一个目标元素或另一个组件的组件时，通过设置 `inheritAttrs` 到 `false`，这些默认行为将会被去掉。详情	√	√	x

# 实例 property

实例 property	描述	H5	App端	微信小程序	说明
$data	组件实例观察的数据对象。组件实例代理了对其 `data` 对象 `property` 的访问。详情	√	√	√
$props	当前组件接收到的 `props` 对象。组件实例代理了对其 `props` 对象 `property` 的访问。详情	√	√	√
$el	组件实例使用的根 `DOM` 元素。详情	√	x	x
$options	用于当前组件实例的初始化选项。需要在选项中包含自定义 `property` 时会有用处。详情	√	√	√
$parent	父实例，如果当前实例有的话。详情	√	√	√	H5端 `view`、`text` 等内置标签是以 `Vue` 组件方式实现，`$parent` 会获取这些到内置组件，导致的问题是 `this.$parent` 与其他平台不一致，解决方式是使用 `this.$parent.$parent` 获取或自定义组件根节点由 `view` 改为 `div`
$root	当前组件树的根组件实例。如果当前实例没有父实例，此实例将会是其自己。详情	√	√	√
$slots	用来访问被插槽分发的内容。每个具名插槽有其相应的 `property` (例如：`v-slot:foo` 中的内容将会在 `this.$slots.foo` 中被找到)。详情	√	√	√
$refs	一个对象，持有注册过 `ref attribute` 的所有 `DOM` 元素和组件实例。详情	√	√	√	非H5端只能用于获取自定义组件，不能用于获取内置组件实例（如：`view`、`text`），`uni-app x` 内置组件绑定 `ref` 会返回组件根节点的引用。
$attrs	包含了父作用域中不作为组件 `props` 或自定义事件。详情	√	√	x	-

# 实例方法

实例方法	描述	H5	App端	微信小程序
$watch	侦听组件实例上的响应式 `property` 或函数计算结果的变化。详情	√	√	√
$emit	触发当前实例上的事件。附加参数都会传给监听器回调。详情	√	√	√
$forceUpdate	迫使组件实例重新渲染。注意它仅仅影响实例本身和插入插槽内容的子组件，而不是所有子组件。详情	√	√	√
$nextTick	将回调延迟到下次 `DOM` 更新循环之后执行。在修改数据之后立即使用它，然后等待 `DOM` 更新。详情	√	√	√

# 指令

Vue 指令	描述	H5	App端	微信小程序	说明
v-text	更新元素的 `textContent`。详情	√	√	x
v-html	更新元素的 `innerHTML`。详情	√	√	√	微信小程序会被转成 `rich-text`
v-show	根据表达式的真假值，切换元素的 `display CSS property`。详情	√	√	√
v-if	根据表达式的真假值来有条件地渲染元素。详情	√	√	√
v-else	为 `v-if` 或者 `v-else-if` 添加`“else 块”`。详情	√	√	√
v-else-if	表示 `v-if` 的`“else if 块”`。可以链式调用。详情	√	√	√
v-for	基于源数据多次渲染元素或模板块。详情	√	√	√
v-on	绑定事件监听器。详情	√	√	√
v-bind	动态地绑定一个或多个 `attribute`，或一个组件 `prop` 到表达式。详情	√	√	√
v-model	在表单控件或者组件上创建双向绑定。详情	√	√	√
v-slot	提供具名插槽或需要接收 `prop` 的插槽。详情	√	√	√
v-pre	跳过这个元素和它的子元素的编译过程。详情	√	√	x
v-cloak	这个指令保持在元素上直到关联组件实例结束编译。详情	√	x	x
v-once	只渲染元素和组件一次。详情	√	√	x
v-is	在 `DOM` 内模板使用时，模板受原生 `HTML` 解析规则的约束。详情	√	x	x	-

# 特殊属性

特殊属性	描述	H5	App端	微信小程序	说明
key	`key` 的特殊 `attribute` 主要用在 `Vue` 的虚拟 `DOM` 算法，在新旧 `nodes` 对比时辨识 `VNodes`。详情	√	√	√
ref	ref 被用来给元素或子组件注册引用信息。详情	√	√	√	非 H5 平台只能获取 `vue` 组件实例不能获取到内置组件实例
is	使用动态组件。详情	√	√	x	-

# 内置组件

内置组件	描述	H5	App端	微信小程序
component	渲染一个“元组件”为动态组件。依 `is` 的值，来决定哪个组件被渲染。详情	√	√	x
transition	作为单个元素/组件的过渡效果。详情	√	x	x
transition-group	作为多个元素/组件的过渡效果。详情	√	x	x
keep-alive	包裹动态组件时，会缓存不活动的组件实例，而不是销毁它们，主要用于保留组件状态或避免重新渲染。详情	√	x	x
slot	作为组件模板之中的内容分发插槽。`slot` 元素自身将被替换。详情	√	√	√
teleport	将模板的一部分移动到 `DOM` 中 `Vue app` 之外的其他位置。详情	√	x	x	-

# 响应性 API

# 响应性基础 API

响应性基础 API	描述	H5	App端	微信小程序
reactive	返回对象的响应式副本。详情	√	√	√
readonly	获取一个对象 (响应式或纯对象) 或 `ref` 并返回原始代理的只读代理。详情	√	√	√
isProxy	检查对象是 `reactive` 还是 `readonly`创建的代理。详情	√	√	√
isReactive	检查对象是否是 `reactive`创建的响应式 `proxy`。详情	√	√	√
isReadonly	检查对象是否是由`readonly`创建的只读代理。详情	√	√	√
toRaw	返回 `reactive` 或 `readonly` 代理的原始对象。详情	√	√	√
markRaw	标记一个对象，使其永远不会转换为代理。返回对象本身。详情	√	√	√
shallowReactive	创建一个响应式代理，该代理跟踪其自身 `property` 的响应性，但不执行嵌套对象的深度响应式转换 (暴露原始值)。详情	√	√	√
shallowReadonly	创建一个代理，使其自身的 `property` 为只读，但不执行嵌套对象的深度只读转换 (暴露原始值)。详情	√	√	√

# Refs

Refs	描述	H5	App端	微信小程序
ref	接受一个内部值并返回一个响应式且可变的 `ref` 对象。`ref` 对象具有指向内部值的单个 property `.value`。详情	√	√	√
unref	如果参数为 `ref`，则返回内部值，否则返回参数本身。这是 `val = isRef(val) ? val.value : val`。详情	√	√	√
toRef	可以用来为源响应式对象上的 `property` 性创建一个 `ref`。然后可以将 `ref` 传递出去，从而保持对其源 `property` 的响应式连接。详情	√	√	√
toRefs	将响应式对象转换为普通对象，其中结果对象的每个 `property` 都是指向原始对象相应 `property` 的`ref`。详情	√	√	√
isRef	检查值是否为`ref`对象详情	√	√	√
customRef	创建一个自定义的 `ref`，并对其依赖项跟踪和更新触发进行显式控制。详情	√	√	√
shallowRef	创建一个 `ref`，它跟踪自己的 `.value` 更改，但不会使其值成为响应式的。详情	√	√	√
triggerRef	手动执行与 `shallowRef` 关联的任何效果。详情	√	√	√

# Computed 与 watch

Computed 与 watch	描述	H5	App端	微信小程序
computed	使用 `getter` 函数，并为从 `getter` 返回的值返回一个不变的响应式 `ref` 对象。详情	√	√	√
watchEffect	在响应式地跟踪其依赖项时立即运行一个函数，并在更改依赖项时重新运行它。详情	√	√	√
watch	`watch` API 与选项式 API `this.$watch` (以及相应的 `watch` 选项) 完全等效。`watch` 需要侦听特定的 `data` 源，并在单独的回调函数中副作用。详情	√	√	√

# 组合式 API

组合式 API	描述	H5	App端	微信小程序
setup	一个组件选项，在创建组件之前执行，一旦 `props` 被解析，并作为组合式 `API` 的入口点。详情	√	√	√
生命周期钩子	可以使用直接导入的 `onX` 函数注册生命周期钩子。详情	√	√	√
Provide / Inject	provide 和 inject 启用依赖注入。只有在使用当前活动实例的 `setup()` 期间才能调用这两者。详情	√	√	√
getCurrentInstance	允许访问对高级使用或库创建者有用的内部组件实例。详情	√	√	√

# 全局变量

实现全局变量的方式需要遵循 Vue 单文件模式的开发规范。详细参考：uni-app全局变量的几种实现方式。

# 其他配置

Vue 组件编译到小程序平台的时候会编译为对应平台的组件，部分小程序平台支持 options 选项（具体选项参考对应小程序平台文档的自定义组件部分），一般情况默认即可，如有特殊需求可在 Vue 组件中增加 options 属性。

属性	类型	默认值	描述	平台兼容性
multipleSlots	Boolean	true	在组件定义时的选项中启动多slot支持
styleIsolation	String	apply-shared	组件样式隔离方式，具体配置选项参见：组件样式隔离	微信小程序
addGlobalClass	Boolean	true	~~这个选项等价于设置 styleIsolation: apply-shared ，但设置了 styleIsolation 选项后这个选项会失效~~	微信小程序
virtualHost	Boolean	false	将自定义节点设置成虚拟的，更加接近Vue组件的表现。我们不希望自定义组件的这个节点本身可以设置样式、响应 flex 布局等，而是希望自定义组件内部的第一层节点能够响应 flex 布局或者样式由自定义组件本身完全决定，启用后可以通过 mergeVirtualHostAttributes 合并合并组件虚拟节点外层属性	微信小程序、支付宝小程序（默认值为 true）、抖音小程序（4.02+）

export default {
  props: ['data'],
  data(){ return { } },
  options: {
    virtualHost: true
  }
}

# 常见问题

# 1. 如何获取上个页面传递的数据

在 onLoad 里得到，onLoad 的参数是其他页面打开当前页面所传递的数据。

# 2. 如何设置全局的数据和全局的方法

uni-app 内置了 Vuex ，在app里的使用，可参考 hello-uniapp store/index.js。

	//store.js
	import {createStore} from 'vuex'
	const store = createStore({
		state: {...},
		mutations: {...},
		actions: {...}
	})
	export default store

	//main.js
	import App from './App'
	import {createSSRApp} from 'vue'
	import store from './store'
	export function createApp() {
		const app = createSSRApp(App)
		app.use(store)
		return {
			app
		}
	}

	//test.vue 使用时：
	import {mapState,mapMutations} from 'vuex'

# 3. 如何捕获 app 的 onError

由于 onError 并不是完整意义的生命周期，所以只提供一个捕获错误的方法，在 app 的根组件上添加名为 onError 的回调函数即可。如下：

	export default {
	   // 只有 app 才会有 onLaunch 的生命周期
		onLaunch () {
		   // ...
		},

		// 捕获 app error
		onError (err) {
		   console.log(err)
		}
	}

# 4. 组件属性设置不生效解决办法

当重复设置某些属性为相同的值时，不会同步到view层。例如：每次将scroll-view组件的scroll-top属性值设置为0，只有第一次能顺利返回顶部。这和props的单向数据流特性有关，组件内部scroll-top的实际值改动后，其绑定的属性并不会一同变化。

解决办法有两种（以scroll-view组件为例）：

监听scroll事件，记录组件内部变化的值，在设置新值之前先设置为记录的当前值

	<scroll-view scroll-y="true" :scroll-top="scrollTop" @scroll="scroll"></scroll-view>

export default {
    data() {
        return {
            scrollTop: 0,
            old: {
                scrollTop: 0
            }
        }
    },
    methods: {
        scroll: function(e) {
            this.old.scrollTop = e.detail.scrollTop
        },
        goTop: function(e) {
            this.scrollTop = this.old.scrollTop
            this.$nextTick(function() {
                this.scrollTop = 0
            });
        }
    }
}

监听scroll事件，获取组件内部变化的值，实时更新其绑定值

	<scroll-view scroll-y="true" :scroll-top="scrollTop" @scroll="scroll"></scroll-view>

	export default {
		data() {
			return {
				scrollTop: 0,
			}
		},
		methods: {
			scroll: function(e) {
				// 如果使用此方法，请自行增加防抖处理
				this.scrollTop = e.detail.scrollTop
			},
			goTop: function(e) {
				this.scrollTop = 0
			}
		}
	}