Skip to content

U
unidocs-uni-app-x-zh

DCloud / unidocs-uni-app-x-zh

通知 144
Star 2
Fork 33
U
unidocs-uni-app-x-zh
提交 629925bb 编写于 作者: D DCloud_LXH
浏览文件
操作

Merge branch 'vue'

上级 e1c2390c 565bc745
展开全部 隐藏空白更改
内联 并排
Showing with 4267 addition and 1171 deletion
docs/.vuepress/config/navbar.js
浏览文件 @ 629925bb
......@@ -34,6 +34,11 @@ export const navbar = [
type: 'link',
link: '/uts/'
},
{
text: 'VUE',
type: 'link',
link: '/vue/'
},
{
text: '全局文件',
type: 'link',
......
docs/.vuepress/markdown/inject-json-to-md.js
浏览文件 @ 629925bb
......@@ -43,7 +43,7 @@ try {
pageInstanceJson = require('../utils/pageInstanceJson.json')
} catch (error) {}
function getRegExp(key) {
function getRegExp(key, text) {
return new RegExp(`<!--\\s*${key}.([\\w\\W]+[^\\s])\\s*-->`)
}
......
docs/.vuepress/utils/vueJson.json
浏览文件 @ 629925bb
因为 它太大了无法显示 source diff 。你可以改为 查看blob。
docs/_sidebar.md
浏览文件 @ 629925bb
......@@ -7,8 +7,6 @@
* [复杂列表开发指南](tutorial/stickynestlist.md)
* [全局变量与状态管理](tutorial/store.md)
* [几种组件标记的概念澄清](tutorial/idref.md)
* vue 框架
* [概述](vue/README.md)
* [web端开发指南](web/README.md)
* 运行和调试
* [真机运行](https://uniapp.dcloud.net.cn/tutorial/run/run-app.html)
......
docs/component/README.md
浏览文件 @ 629925bb
# uvue组件概述
uni-app x支持的组件包括：
- 内置基础组件
- 自定义vue组件
- uts组件插件
除了微信小程序，其他平台不支持的小程序wxml组件。
支持[easycom](https://uniapp.dcloud.net.cn/component/index.html#easycom)。
内置组件比较简单，扩展组件的2种方式详细介绍下
- 自定义vue组件
在components目录新建一个uvue/vue文件，按vue组件规范编写代码。
组件界面通过uvue构造，script使用uts编写。
返回的类型是组件实例[ComponentPublicInstance](../vue/)。
- uts组件插件
`uts组件插件`的名称可能有点拗口，这是因为是相对于另一个分类`uts api插件`。
它们同属于`uts插件`，是[uni_modules](https://uniapp.dcloud.net.cn/plugin/uni_modules.html)。api插件指能力扩展，比如蓝牙api。而组件插件指界面元素扩展，比如video、map、lottie动画等。
uts组件插件，指把原生的、需要在界面上显示的、内嵌于页面中整体排版的组件，编写uts代码调用原生sdk，通过uni_modules插件的方式集成到uni-app项目中。比如
* lottie组件，使用uts调用原生的lottie sdk来开发组件，再引入页面中。[详见](https://ext.dcloud.net.cn/plugin?name=uni-animation-view)
* video组件，其实官方的video，也是用uts组件插件实现的。[详见](https://gitcode.net/dcloud/uni-component/-/tree/master/uni_modules/uni-video)
uts组件插件，主要用于原生sdk涉及界面时，将其封装为界面组件。当然uts组件也是全端支持的。上述lottie组件也支持web端。
在app端，它的内部界面是由原生sdk绘制的，而不是uvue代码绘制的。通过封装嵌入到uvue/nvue页面中。
一个uts插件都是可以同时兼容uni-app x和uni-app js引擎版的。目前js引擎版仅支持内嵌于nvue页面中。所以上述lottie组件也是可以在app-nvue页面中使用的。
uts组件的返回类型是dom元素[Element](../dom/element.md)
uts组件插件的开发教程，[详见](https://uniapp.dcloud.net.cn/plugin/uts-component.html)
**vue组件兼容性及注意事项：**
## props
- 支持[对象方式](https://cn.vuejs.org/guide/components/props.html#props-declaration)声明。从 4.0+ 支持字符串数组方式声明。使用字符串数组方式声明时，所有 prop 类型均为 any | null。
- 仅支持直接在 `export default` 内部声明，不支持其他位置定义后，在 `export default` 中引用。
- 复杂数据类型需要通过 `PropType` 标记类型，[详见](https://cn.vuejs.org/guide/typescript/options-api.html#typing-component-props)。
- `type` 不支持使用自定义的构造函数。
::: preview
> 选项式 API
```ts
<script lang="uts">
export default {
// 字符串数组方式声明，所有 prop 类型均为 any | null
props: ['num', 'str', 'obj', 'arr']
}
</script>
```
> 组合式 API
```ts
<script setup lang="uts">
// 字符串数组方式声明，所有 prop 类型均为 any | null
const props = defineProps(['num', 'str', 'obj', 'arr'])
</script>
```
:::
::: preview
> 选项式 API
```ts
<script lang="uts">
type Obj = { a: number }
export default {
props: {
num: {
type: Number,
required: true
},
str: {
type: String,
default: 'str',
validator(value: string): boolean {
return value.length > 0
}
},
obj: {
type: UTSJSONObject as PropType<Obj>,
default: (): Obj => ({ a: 1 } as Obj)
},
arr: {
type: Array as PropType<number[]>,
default: (): number[] => [1, 2, 3]
}
}
}
</script>
```
> 组合式 API
```ts
<script setup lang="uts">
type Obj = { a: number }
const props = defineProps({
num: {
type: Number,
required: true
},
str: {
type: String,
default: 'str',
validator(value : string) : boolean {
return value.length > 0
}
},
obj: {
type: UTSJSONObject as PropType<Obj>,
default: () : Obj => ({ a: 1 } as Obj)
},
arr: {
type: Array as PropType<number[]>,
default: () : number[] => [1, 2, 3]
}
})
</script>
```
:::
## 自定义组件 v-model 绑定复杂表达式 @v-model-complex-expression
自定义组件 `v-model` 绑定复杂表达式时，需要通过 `as` 指定类型(仅App-Android 平台)。
::: preview
> 选项式 API
```ts
<template>
<input v-model="obj.str as string" />
</template>
<script lang="uts">
type Obj = {
str : string
}
export default {
data() {
return {
obj: {
str: "str"
} as Obj
}
}
}
</script>
```
> 组合式 API
```ts
<template>
<input v-model="obj.str as string" />
</template>
<script setup lang="uts">
type Obj = {
str: string
}
const obj = reactive({
str: "str"
} as Obj)
</script>
```
:::
## 作用域插槽的类型
作用域插槽需在组件中指定插槽数据类型
::: preview
> 选项式 API
```ts
// components/Foo.uvue
<template>
<slot msg="test msg" />
</template>
<script lang="uts">
import { SlotsType } from 'vue'
export default {
slots: Object as SlotsType<{
default: { msg: string }
}>
}
</script>
// page.uvue
<template>
<Foo>
<template v-slot="{ msg }">
<text>{{ msg }}</text>
</template>
</Foo>
</template>
<script lang="uts">
import Foo from './Foo.uvue'
export default {
components: { Foo },
}
</script>
```
> 组合式 API
```ts
// components/Foo.uvue
<template>
<slot msg="test msg" />
</template>
<script setup lang="uts">
defineSlots<{
default(props: { msg: string }): null
}>()
</script>
// page.uvue
<template>
<Foo>
<template v-slot="{ msg }">
<text>{{ msg }}</text>
</template>
</Foo>
</template>
<script setup lang="uts">
import Foo from './Foo.uvue'
</script>
```
:::
## ref
在 `uni-app js 引擎版`中，非 `Web端` 只能用于获取自定义组件，不能用于获取内置组件实例（如：`view`、`text`）。\
在 `uni-app x` 中，内置组件会返回组件根节点的引用，自定义组件会返回组件实例。
**注意事项：**
- 如果多个节点或自定义组件绑定相同 `ref` 属性，将获取到最后一个节点或组件实例的引用。
- 在 `v-for` 循环时，绑定 `ref` 属性会获取到节点或组件实例的集合。
- 在 `uni-app x` 中，要访问 `$refs` 中的属性，需要使用索引方式。
::: preview
> uni-app x
```ts
// 选项式 API
<template>
<view>
<text ref="textRef">text node</text>
<Foo ref="fooRef" />
</view>
</template>
<script lang="uts">
import type { ComponentPublicInstance } from 'vue'
export default {
onReady() {
const text = this.$refs["textRef"] as Element
const foo = this.$refs["fooRef"] as ComponentPublicInstance
}
}
</script>
// 组合式 API
<template>
<view>
<text ref="textRef">text node</text>
<Foo ref="fooRef" />
</view>
</template>
<script setup lang="uts">
import type { ComponentPublicInstance } from 'vue'
import Foo from './Foo.uvue'
const textRef = ref<null | Element>(null)
const fooRef = ref<null | ComponentPublicInstance>(null)
</script>
```
> uni-app js 引擎版
```ts
<template>
<view>
<text ref="textRef">text node</text>
<Foo ref="fooRef" />
</view>
</template>
<script lang="ts">
import type { ComponentPublicInstance } from 'vue'
export default {
onReady() {
const text = this.$refs.textRef as Element // 仅H5端支持
const foo = this.$refs.fooRef as ComponentPublicInstance
}
}
</script>
```
:::
## 监听页面生命周期
`4.0` 起可通过组合式 API 实现组件中监听页面生命周期，[示例代码](https://gitcode.net/dcloud/hello-uvue/-/blob/alpha/pages/composition-api/lifecycle/component-lifecycle/component-lifecycle.uvue)。
`4.0` 起可通过组合式 API 实现组件中监听页面生命周期，[示例代码](../vue/component.md#component-lifecycle)。
## 调用组件方法@methods
需要把组件分为 内置组件、easycom组件、非easycom组件，这3种组件有不同的方法调用方式。
需要把组件分为 内置组件、easycom组件、非easycom组件，这3种组件有不同的方法调用方式。[详情](../vue/component.md#page-call-component-method)
### 内置组件的方法调用或设置属性
> 3.93+ 支持
使用 `this.$refs` 获取组件并as转换为组件对应的element类型，通过 `.`操作符 调用组件方法或设置属性。
**语法**
```(this.$refs['组件ref属性值'] as Uni[xxx]Element).foo();```
**内置组件的element类型规范**
Uni`组件名(驼峰)`Element
如：
`<button>`: UniButtonElement
`<picker-view>`: UniPickerViewElement
**示例代码**
::: preview
> 选项式 API
```html
<template>
<slider ref="sliderRef" />
</template>
<script lang="uts">
export default {
onReady() {
// value 为属性
(this.$refs["sliderRef"] as UniSliderElement).value = 90;
//此处注意 sliderRef 必须存在，如不存在，把 null as 成 UniSliderElement 会引发崩溃
}
}
</script>
```
> 组合式 API
```html
<template>
<slider ref="sliderRef" />
</template>
<script setup lang="uts">
const sliderRef = ref<null | UniSliderElement>(null)
onReady(() => {
(sliderRef.value!).value = 90
})
</script>
```
:::
**bug&tips**
- 目前uts组件，即封装原生ui给uni-app或uni-app x的页面中使用，类型与内置组件的 Uni`组件名(驼峰)`Element 方式相同。目前没有代码提示。
使用 `this.$refs` 获取组件并as转换为组件对应的element类型，通过 `.`操作符 调用组件方法或设置属性。[详情](../vue/component.md#call-builtin-component-method)
### easycom组件调用方法或设置属性@method_easycom
> 3.97+ 支持 uni_modules 目录下的组件
easycom组件，用法和内置组件一样。也是使用 `this.$refs` 获取组件并转换为组件的类型，通过 `.`操作符 调用组件方法或设置属性。
**语法**
```(this.$refs['组件ref属性值'] as 驼峰ComponentPublicInstance).foo();```
**easycom组件的类型规范**
组件标签名首字母大写，驼峰+ComponentPublicInstance
如：
`<test/>` 类型为：TestComponentPublicInstance
`<uni-data-checkbox/>` 类型为：UniDataCheckboxComponentPublicInstance
**示例代码**
假使有一个 `Foo` 组件，其有若干方法 `foo1` 等，如下。
::: preview
> 选项式 API
```html
<script lang="uts">
export default {
methods: {
foo1() {
console.log("foo1 triggered");
},
foo2(num : number) {
console.log('foo2 triggered by num:', num);
},
foo3(callback : (() => void)) {
callback()
}
}
}
</script>
```
> 组合式 API
```html
<script setup lang="uts">
const foo1 = () => {
console.log("foo1 triggered");
}
const foo2 = (num : number) => {
console.log('foo2 triggered by num:', num);
}
const foo3 = (callback : (() => void)) => {
callback()
}
defineExpose({
foo1,
foo2,
foo3,
})
</script>
```
:::
`Foo` 组件符合[easycom规范](https://uniapp.dcloud.net.cn/component/#easycom)
那么在页面中调用 `Foo` 组件的方法如下：
::: preview
> 选项式 API
```html
<template>
<Foo ref="fooRef" />
</template>
<script lang="uts">
export default {
onReady() {
//注意组件必须存在，注意类型首字母大写
const fooRef = (this.$refs["fooRef"] as FooComponentPublicInstance)
fooRef.foo1();
fooRef.foo2(100);
fooRef.foo3(() => {console.log('foo3 triggered')});
}
}
</script>
```
> 组合式 API
```html
<template>
<Foo ref='fooRef' />
</template>
<script setup lang="uts">
const fooRef = ref<null | FooComponentPublicInstance>(null)
onReady(() => {
(fooRef.value!).foo1();
(fooRef.value!).foo2(100);
(fooRef.value!).foo3(() => {console.log('foo3 triggered')});
})
</script>
```
:::
easycom组件，用法和内置组件一样。也是使用 `this.$refs` 获取组件并转换为组件的类型，通过 `.`操作符 调用组件方法或设置属性。[详情](../vue/component.md#call-easycom-component-method)
### 其它自定义组件的方法调用使用callMethod@$callMethod
如果不是内置组件，也不是easycom组件，那么无法使用`.`操作符了。
此时需使用 `this.$refs` 获取组件实例，然后通过 `$callMethod` 调用组件的方法。也就是把组件的方法名、参数，当做callMethod的参数来传递。此时也就没有`.`操作符那样的代码提示和校验了。
callMethod可用于所有自定义组件，包括easycom组件也可以使用，只不过easycom组件有更简单的用法。
**语法**
```(this.$refs['组件ref属性值'] as ComponentPublicInstance).$callMethod('方法名', ...args)```
**组件类型**
ComponentPublicInstance
页面示例代码 `page.uvue`
::: preview
> 选项式 API
```html
<template>
<Foo ref="fooRef" />
</template>
<script lang="uts">
import Foo from './Foo.uvue'
export default {
components: {
Foo
},
onReady() {
const fooRef = this.$refs['fooRef'] as ComponentPublicInstance
fooRef.$callMethod('foo1')
const res = fooRef.$callMethod('foo2', 100, 10)
console.log('res of foo2', res)
fooRef.$callMethod('foo3', () => {
console.log('foo3 triggered')
})
}
}
</script>
```
> 组合式 API
```html
<template>
<Foo ref="fooRef" />
</template>
<script setup lang="uts">
import Foo from './Foo.uvue'
const fooRef = ref<null | ComponentPublicInstance>(null)
onReady(() => {
(fooRef.value!).$callMethod('foo1')
const res = (fooRef.value!).$callMethod('foo2', 100, 10)
console.log('res of foo2', res);
(fooRef.value!).$callMethod('foo3', () => {
console.log('foo3 triggered')
})
})
</script>
```
:::
组件示例代码 `Foo.uvue`
::: preview
> 选项式 API
```html
<script lang="uts">
export default {
methods: {
foo1() {
console.log("foo1 triggered");
},
foo2(num1 : number, num2: number){
console.log(`foo2 triggered by num1: ${num1}, num2: ${num2}`)
return num1 + num2
},
foo3(callback : (() => void)) {
callback()
}
}
}
</script>
```
> 组合式 API
```html
<script setup lang="uts">
const foo1 = () => {
console.log("foo1 triggered");
}
const foo2 = (num1 : number, num2: number): number => {
console.log(`foo2 triggered by num1: ${num1}, num2: ${num2}`)
return num1 + num2
}
const foo3 = (callback : (() => void)) => {
callback()
}
defineExpose({
foo1,
foo2,
foo3,
})
</script>
```
:::
**注意：**
- App-Android 平台 `4.0` 版本开始支持 `$callMethod` 调用 `defineExpose` 导出的方法
- Web 平台、App-iOS 平台 `4.13` 版本开始支持 `$callMethod` 调用 `defineExpose` 导出的方法
此时需使用 `this.$refs` 获取组件实例，然后通过 `$callMethod` 调用组件的方法。也就是把组件的方法名、参数，当做callMethod的参数来传递。此时也就没有`.`操作符那样的代码提示和校验了。[详情](../vue/component.md#call-component-method)
## 如何开发同时兼容 uni-app x 和 uni-app 的组件
......
docs/page.md
浏览文件 @ 629925bb
......@@ -2,7 +2,7 @@
本文未包括页面生命周期的详细介绍，需另见 [页面](https://uniapp.dcloud.net.cn/tutorial/page.html)
## 页面生命周期
## 页面生命周期 @lifecycle
<!-- PAGEINSTANCE.lifeCycle.compatibility -->
......@@ -37,14 +37,17 @@ export default {
this.post_id = event["post_id"] ?? "";
// 可根据详情页id继续联网请求数据...
},
}
```
::: warning 注意
- OnLoadOptions类型，可不填。不填时可自动推导。
- OnLoadOptions类型目前在web和Android的运行时类型不统一，web是对象，Android是map。[详见issues](https://issues.dcloud.net.cn/pages/issues/detail?id=967)
* 但仍然可以通过上述示例代码跨平台的获取入参。
* 后续版本会统一类型为UTSJSONObject。
- 但仍然可以通过上述示例代码跨平台的获取入参。
- 后续版本会统一类型为UTSJSONObject。
:::
## 页面及组件生命周期流程图@lifeCycleFlow
## 页面及组件生命周期流程图 @lifecycleflow
![](./static/uni-app-lifecycle-vue3.png)#{.zooming width=1000 margin=auto}
docs/vue/README.md
浏览文件 @ 629925bb
此差异已折叠。
docs/vue/_sidebar.md 0 → 100644
浏览文件 @ 629925bb
- [概述](./README.md)
- [数据绑定模型](./data-bind.md)
- [组件模型](./component.md)
- [修饰符](./modifier.md)
- [全局 API](./global-api.md)
- [组合式 API](./composition-api.md)
- [选项式 API](./options-api.md)
- [内置内容](./built-in.md)
- [进阶 API](./advanced-api.md)
- [vue 生态](./others.md)
docs/vue/advanced-api.md 0 → 100644
浏览文件 @ 629925bb
# 进阶 API
## 渲染函数
<!-- VUEJSON.render_function.compatibility -->
### 示例代码 @example
#### h()
创建虚拟 DOM 节点 (vnode)。
- 详细信息
第一个参数既可以是一个字符串 (用于原生元素) 也可以是一个 Vue 组件定义。第二个参数是要传递的 prop，第三个参数是子节点。
当创建一个组件的 vnode 时，子节点必须以插槽函数进行传递。如果组件只有默认槽，可以使用单个插槽函数进行传递。否则，必须以插槽函数的对象形式来传递。
为了方便阅读，当子节点不是插槽对象时，可以省略 prop 参数。
- 示例 [详情](<!-- VUEJSON.E_render-function.render_render-options.gitUrl -->)
::: preview <!-- VUEJSON.E_render-function.render_render-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_render-function.render_render-options.code -->
> 组合式 API
<!-- VUEJSON.E_render-function.render_render-composition.code -->
:::
#### mergeProps()
合并多个 props 对象，用于处理含有特定的 props 参数的情况。
- 详细信息
mergeProps() 支持以下特定 props 参数的处理，将它们合并成一个对象。
- class
- style
- onXxx 事件监听器——多个同名的事件监听器将被合并到一个数组。
如果你不需要合并行为而是简单覆盖，可以使用原生 object spread 语法来代替。
- 示例 [详情](<!-- VUEJSON.E_render-function.mergeProps_mergeProps-options.gitUrl -->)
::: preview <!-- VUEJSON.E_render-function.mergeProps_mergeProps-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_render-function.mergeProps_mergeProps-options.code -->
> 组合式 API
<!-- VUEJSON.E_render-function.mergeProps_mergeProps-composition.code -->
:::
#### cloneVNode()
克隆一个 vnode。
- 详细信息
返回一个克隆的 vnode，可在原有基础上添加一些额外的 prop。
Vnode 被认为是一旦创建就不能修改的，你不应该修改已创建的 vnode 的 prop，而应该附带不同的/额外的 prop 来克隆它。
Vnode 具有特殊的内部属性，因此克隆它并不像 object spread 一样简单。cloneVNode() 处理了大部分这样的内部逻辑。
- 示例 [详情](<!-- VUEJSON.E_render-function.cloneVNode_cloneVNode-options.gitUrl -->)
::: preview <!-- VUEJSON.E_render-function.cloneVNode_cloneVNode-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_render-function.cloneVNode_cloneVNode-options.code -->
> 组合式 API
<!-- VUEJSON.E_render-function.cloneVNode_cloneVNode-composition.code -->
:::
#### isVNode()
判断一个值是否为 vnode 类型。
- 示例 [详情](<!-- VUEJSON.E_render-function.isVNode_isVNode-options.gitUrl -->)
::: preview <!-- VUEJSON.E_render-function.isVNode_isVNode-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_render-function.isVNode_isVNode-options.code -->
> 组合式 API
<!-- VUEJSON.E_render-function.isVNode_isVNode-composition.code -->
:::
#### resolveComponent()
按名称手动解析已注册的组件。
- 详细信息
备注：如果你可以直接引入组件就不需使用此方法。
为了能从正确的组件上下文进行解析，`resolveComponent()` 必须在 `setup()` 或渲染函数内调用。
如果组件未找到，会抛出一个运行时警告，并返回组件名字符串。
- 示例 [详情](<!-- VUEJSON.E_render-function.resolveComponent_resolveComponent-options.gitUrl -->)
::: preview <!-- VUEJSON.E_render-function.resolveComponent_resolveComponent-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_render-function.resolveComponent_resolveComponent-options.code -->
> 组合式 API
<!-- VUEJSON.E_render-function.resolveComponent_resolveComponent-composition.code -->
:::
#### withDirectives()
用于给 vnode 增加自定义指令。
- 详细信息
用自定义指令包装一个现有的 vnode。第二个参数是自定义指令数组。每个自定义指令也可以表示为 `[Directive, value, argument, modifiers]` 形式的数组。如果不需要，可以省略数组的尾元素。
- 示例 [详情](<!-- VUEJSON.E_render-function.withDirectives_withDirectives-options.gitUrl -->)
::: preview <!-- VUEJSON.E_render-function.withDirectives_withDirectives-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_render-function.withDirectives_withDirectives-options.code -->
> 组合式 API
<!-- VUEJSON.E_render-function.withDirectives_withDirectives-composition.code -->
:::
#### withModifiers()
用于向事件处理函数添加内置 [v-on](./built-in.md#v-on) 修饰符。
docs/vue/built-in.md 0 → 100644
浏览文件 @ 629925bb
# 内置内容
## 指令 @directives
<!-- VUEJSON.directives.compatibility -->
### v-text
更新元素的文本内容。
- 期望的绑定值类型：string
- 详细信息
v-text 将覆盖元素中所有现有的内容。
示例 [详情](<!-- VUEJSON.E_directive.v-text_v-text-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-text_v-text-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-text_v-text-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-text_v-text-composition.code -->
:::
### v-html
更新元素的内容，并且不会被解析。
::: warning 注意
在 `App-android` 平台，`v-html` 指令通过编译为 [rich-text](../component/rich-text.md) 组件实现。因此，`v-html` 指令的内容必须是 `rich-text` 支持的格式, 并且要遵循标签嵌套规则，例如， `swiper` 标签内只允许嵌套 `swiper-item` 标签。\
同时，受限于 `rich-text` 组件不支持 `class` 样式，`v-html` 指令中同样不支持 `class` 样式。\
绑定 `v-html` 的标签内的内容会被忽略，`v-html` 指令的内容会编译为 `rich-text` 组件渲染为该标签的子节点。
:::
示例 [详情](<!-- VUEJSON.E_directive.v-html_v-html-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-html_v-html-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-html_v-html-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-html_v-html-composition.code -->
:::
### v-show
基于表达式值的真假性，来改变元素的可见性。
示例 [详情](<!-- VUEJSON.E_directive.v-show_v-show-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-show_v-show-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-show_v-show-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-show_v-show-composition.code -->
:::
### v-if
基于表达式值的真假性，来条件性地渲染元素或者模板片段。
- 详细信息
当 `v-if` 元素被触发，元素及其所包含的指令/组件都会销毁和重构。如果初始条件是假，那么其内部的内容根本都不会被渲染。
可用于 `<template>` 表示仅包含文本或多个元素的条件块。
示例 [详情](<!-- VUEJSON.E_directive.v-if_v-if-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-if_v-if-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-if_v-if-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-if_v-if-composition.code -->
:::
### v-for
基于原始数据多次渲染元素或模板块。
- 期望的绑定值类型：`Array | UTSJSONObject | number | string | Iterable`
- 详细信息
指令值必须使用特殊语法 `alias in expression` 为正在迭代的元素提供一个别名：
```vue
<view v-for="item in items">
{{ item.text }}
</view>
```
`v-for` 的默认方式是尝试就地更新元素而不移动它们。要强制其重新排序元素，你需要用特殊 attribute `key` 来提供一个排序提示：
```vue
<view v-for="item in items" :key="item.id">
{{ item.text }}
</view>
```
示例 [详情](<!-- VUEJSON.E_directive.v-for_v-for-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-for_v-for-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-for_v-for-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-for_v-for-composition.code -->
:::
### v-on
给元素绑定事件监听器。
- 缩写：`@`
- 期望的绑定值类型：`Function | Object (不带参数)`
- 参数：`event` (使用对象语法则为可选项)
- 修饰符
- `.stop` - 调用 `event.stopPropagation()`
- `.once` - 最多触发一次处理函数。
- [事件修饰符](https://uniapp.dcloud.net.cn/tutorial/vue3-basics.html#%E4%BA%8B%E4%BB%B6%E4%BF%AE%E9%A5%B0%E7%AC%A6) 只支持 `stop` 和 `once`。
示例 [详情](<!-- VUEJSON.E_directive.v-on_v-on-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-on_v-on-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-on_v-on-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-on_v-on-composition.code -->
:::
### v-bind
动态的绑定一个或多个 attribute，也可以是组件的 prop。
- 缩写：
- `:` 或者 `.` (当使用 `.prop` 修饰符)
- 值可以省略 (当 attribute 和绑定的值同名时)
- 期望：`any (带参数) | Object (不带参数)`
- 参数：`attrOrProp (可选的)`
- 用途
当用于绑定 `class` 或 `style` attribute，`v-bind` 支持额外的值类型如数组或对象。
当用于组件 props 绑定时，所绑定的 props 必须在子组件中已被正确声明。
当不带参数使用时，可以用于绑定一个包含了多个 attribute 名称-绑定值对的对象。
示例 [详情](<!-- VUEJSON.E_directive.v-bind_v-bind-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-bind_v-bind-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-bind_v-bind-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-bind_v-bind-composition.code -->
:::
### v-model
在表单输入元素或组件上创建双向绑定。
- 期望的绑定值类型：根据表单输入元素或组件输出的值而变化
- 修饰符 <Badge text="仅 Android">
- `.lazy` - 监听 `change` 事件而不是 `input` 事件
- `.number` - 将输入的合法字符串转为数字
- `.trim` - 移除输入内容两端空格
示例 [详情](<!-- VUEJSON.E_directive.v-model_v-model-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-model_v-model-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-model_v-model-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-model_v-model-composition.code -->
:::
### v-pre
跳过该元素及其所有子元素的编译。
- 无需传入
- 详细信息
元素内具有 `v-pre`，所有 Vue 模板语法都会被保留并按原样渲染。最常见的用例就是显示原始双大括号标签及内容。
示例 [详情](<!-- VUEJSON.E_directive.v-pre_v-pre.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-pre_v-pre.webUrl -->
<!-- VUEJSON.E_directive.v-pre_v-pre.code -->
:::
### v-once
仅渲染元素和组件一次，并跳过之后的更新。
- 无需传入
- 详细信息
在随后的重新渲染，元素/组件及其所有子项将被当作静态内容并跳过渲染。这可以用来优化更新时的性能。
示例 [详情](<!-- VUEJSON.E_directive.v-once_v-once-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-once_v-once-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-once_v-once-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-once_v-once-composition.code -->
:::
### v-slot
用于声明具名插槽或是期望接收 props 的作用域插槽。
- 缩写：`#`
- 期望的绑定值类型：能够合法在函数参数位置使用的 JavaScript 表达式。支持解构语法。绑定值是可选的——只有在给作用域插槽传递 props 才需要。
- 参数：插槽名 (可选，默认是 `default`)
- 仅限：
- `<template>`
- [components](./component.md) (用于带有 prop 的单个默认插槽)
示例 [详情](<!-- VUEJSON.E_directive.v-slot_v-slot-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-slot_v-slot-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-slot_v-slot-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-slot_v-slot-composition.code -->
:::
### v-memo
- 期望的绑定值类型：`any[]`
- 详细信息
缓存一个模板的子树。在元素和组件上都可以使用。为了实现缓存，该指令需要传入一个固定长度的依赖值数组进行比较。如果数组里的每个值都与最后一次的渲染相同，那么整个子树的更新将被跳过。举例来说：
```vue
<view v-memo="[valueA, valueB]">
...
</view>
```
当组件重新渲染，如果 `valueA` 和 `valueB` 都保持不变，这个 `<view>` 及其子项的所有更新都将被跳过。实际上，甚至虚拟 DOM 的 vnode 创建也将被跳过，因为缓存的子树副本可以被重新使用。
正确指定缓存数组很重要，否则应该生效的更新可能被跳过。`v-memo` 传入空依赖数组 (`v-memo="[]"`) 将与 `v-once` 效果相同。
v-memo 仅用于性能至上场景中的微小优化，应该很少需要。最常见的情况可能是有助于渲染海量 v-for 列表 (长度超过 1000 的情况)：
当组件的 `selected` 状态改变，默认会重新创建大量的 vnode，尽管绝大部分都跟之前是一模一样的。`v-memo` 用在这里本质上是在说“只有当该项的被选中状态改变时才需要更新”。这使得每个选中状态没有变的项能完全重用之前的 vnode 并跳过差异比较。注意这里 memo 依赖数组中并不需要包含 `item.id`，因为 Vue 也会根据 item 的 `:key` 进行判断。
::: warning 警告
当搭配 `v-for` 使用 `v-memo`，确保两者都绑定在同一个元素上。`v-memo` 不能用在 `v-for` 内部。
:::
`v-memo` 也能被用于在一些默认优化失败的边际情况下，手动避免子组件出现不需要的更新。但是一样的，开发者需要负责指定正确的依赖数组以免跳过必要的更新。
示例 [详情](<!-- VUEJSON.E_directive.v-memo_v-memo-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-memo_v-memo-options.webUrl -->
>选项式 API
<!-- VUEJSON.E_directive.v-memo_v-memo-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-memo_v-memo-composition.code -->
:::
## 组件 @component
- [props](../component/README.md#props)
- [自定义事件](../component/README.md#自定义事件)
- [计算属性和侦听器](../component/README.md#计算属性和侦听器)
- [作用域插槽的类型](../component/README.md#作用域插槽的类型)
- [监听页面生命周期](../component/README.md#监听页面生命周期)
- [vue 与 uvue 不同文件后缀的优先级](../component/README.md#priority)
::: warning 注意
- App 端，如需页面级滚动，根节点必须是 `scroll-view` 标签。
:::
### \<KeepAlive> @keep-alive
<!-- VUEJSON.keep-alive.description -->
<!-- VUEJSON.keep-alive.attribute -->
<!-- VUEJSON.keep-alive.event -->
<!-- VUEJSON.keep-alive.example -->
<!-- VUEJSON.keep-alive.compatibility -->
<!-- VUEJSON.keep-alive.children -->
<!-- VUEJSON.keep-alive.reference -->
### \<Transition> @transition
<!-- VUEJSON.transition.description -->
<!-- VUEJSON.transition.attribute -->
<!-- VUEJSON.transition.event -->
<!-- VUEJSON.transition.example -->
<!-- VUEJSON.transition.compatibility -->
<!-- VUEJSON.transition.children -->
<!-- VUEJSON.transition.reference -->
### \<TransitionGroup> @transition-group
<!-- VUEJSON.transition-group.description -->
<!-- VUEJSON.transition-group.attribute -->
<!-- VUEJSON.transition-group.event -->
<!-- VUEJSON.transition-group.example -->
<!-- VUEJSON.transition-group.compatibility -->
<!-- VUEJSON.transition-group.children -->
<!-- VUEJSON.transition-group.reference -->
### \<Teleport> @teleport
<!-- VUEJSON.teleport.description -->
<!-- VUEJSON.teleport.attribute -->
**注意：**
- App-Android 平台暂不支持动态修改 `to` 属性。
<!-- VUEJSON.teleport.event -->
<!-- VUEJSON.teleport.example -->
<!-- VUEJSON.teleport.compatibility -->
<!-- VUEJSON.teleport.children -->
<!-- VUEJSON.teleport.reference -->
## 特殊元素 @special-elements
### \<template> @template
<!-- VUEJSON.template.description -->
<!-- VUEJSON.template.attribute -->
<!-- VUEJSON.template.event -->
<!-- VUEJSON.template.example -->
<!-- VUEJSON.template.compatibility -->
<!-- VUEJSON.template.children -->
<!-- VUEJSON.template.reference -->
### \<slot> @slot
<!-- VUEJSON.slot.description -->
<!-- VUEJSON.slot.attribute -->
<!-- VUEJSON.slot.event -->
<!-- VUEJSON.slot.example -->
<!-- VUEJSON.slot.compatibility -->
<!-- VUEJSON.slot.children -->
<!-- VUEJSON.slot.reference -->
### \<component> @component
<!-- VUEJSON.component.description -->
<!-- VUEJSON.component.attribute -->
<!-- VUEJSON.component.event -->
<!-- VUEJSON.component.example -->
<!-- VUEJSON.component.compatibility -->
<!-- VUEJSON.component.children -->
<!-- VUEJSON.component.reference -->
## 特殊 Attributes @special-attributes
<!-- VUEJSON.special_attributes.compatibility -->
<!-- VUEJSON.special_attributes.example -->
### key
`key` 这个特殊的 attribute 主要作为 Vue 的虚拟 DOM 算法提示，在比较新旧节点列表时用于识别 vnode。
- 预期：`number | string | symbol`
- 详细信息
在没有 key 的情况下，Vue 将使用一种最小化元素移动的算法，并尽可能地就地更新/复用相同类型的元素。如果传了 key，则将根据 key 的变化顺序来重新排列元素，并且将始终移除/销毁 key 已经不存在的元素。
同一个父元素下的子元素必须具有唯一的 key。重复的 key 将会导致渲染异常。
最常见的用例是与 `v-for` 结合：
```vue
<view>
<text v-for="item in items" :key="item.id">...</text>
</view>
```
也可以用于强制替换一个元素/组件而不是复用它。当你想这么做时它可能会很有用：
- 在适当的时候触发组件的生命周期钩子
- 触发过渡
举例来说：
```vue
<transition>
<text :key="text">{{ text }}</text>
</transition>
```
当 `text` 变化时，`<text>` 总是会被替换而不是更新，因此 transition 将会被触发。
### ref
用于注册模板引用。
- 预期：`string | Function`
- 详细信息
`ref` 用于注册元素或子组件的引用。
使用选项式 API，引用将被注册在组件的 `this.$refs` 对象里：
```vue
<!-- 存储为 this.$refs["textRef"] -->
<text ref="textRef">hello</text>
```
使用组合式 API，引用将存储在与名字匹配的 ref 里：[详情](./component.md#page-call-component-method)
`this.$refs` 也是非响应式的，因此你不应该尝试在模板中使用它来进行数据绑定。
### is
用于绑定动态组件。
- 预期：`string | Component`
docs/vue/component.md 0 → 100644
浏览文件 @ 629925bb
# 组件
## 定义
- 组件是视图层的基本组成单元。
- 组件是一个单独且可复用的功能模块的封装。
每个组件，包括如下几个部分：以组件名称为标记的开始标签和结束标签、组件内容、组件属性、组件属性值。
- 组件名称由尖括号包裹，称为标签，它有开始标签和结束标签。结束标签的`<`后面用`/`来表示结束。结束标签也称为闭合标签。如下面示例的`<component-name>`是开始标签，`</component-name>`是结束标签。
- 在开始标签和结束标签之间，称为组件内容。如下面示例的`content`
- 开始标签上可以写属性，属性可以有多个，多个属性之间用空格分割
- 每个属性通过`=`赋值
## 创建及引用组件 @create-and-import-component
### easycom
传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。`easycom` 将其精简为一步。
只要组件安装在项目的 `components` 目录下或 `uni_modules/插件 id/components` 目录下，并符合 `组件名称/组件名称.(vue|uvue)` 目录结构。就可以不用引用、注册，直接在页面中使用。
- 比如 [uni-rate组件](https://ext.dcloud.net.cn/plugin?id=33)，它导入到项目后，存放在了目录 /uni_modules/uni-rate/uni-rate.vue
同时它的组件名称也叫 uni-rate，所以这样的组件，不用在 script 里注册和引用。如下：
```html
<template>
<view>
<uni-rate></uni-rate><!-- 这里会显示一个五角星，并且点击后会自动亮星 -->
</view>
</template>
<script>
// 这里不用import引入，也不需要在components内注册uni-list组件。template里就可以直接用
// ...
</script>
```
#### uni_modules 组件 @uni-module-components
> uni_module其实不止服务于组件，它可以服务于组件、js库、页面、项目等所有DCloud插件市场所支持的种类。
符合uni_module规范的组件都在项目的`uni_modules`目录下，以插件id为目录存放。（项目模板不放在`uni_modules`目录下）
在HBuilderX中点右键可方便的更新插件，插件作者也可以方便的上传插件。
uni_module有详细的专项文档，请另行查阅[uni_module规范](https://uniapp.dcloud.net.cn/plugin/uni_modules.html)。
#### easycom组件的类型规范 @easycom-component-type
组件标签名首字母大写，`驼峰+ComponentPublicInstance`，如：
`<test/>` 类型为：TestComponentPublicInstance
`<uni-data-checkbox/>` 类型为：UniDataCheckboxComponentPublicInstance
### 手动引入组件 @manual-import-component
在新建一个组件后，如果不符合 easycom 规范，则需要手动引入：
```vue
<!-- 组件 child.vue -->
<template>
<view>Child Component</view>
</template>
<!-- 页面（与 child.vue 组件在同级目录 -->
<template>
<view>
<child ref="component1"></child>
</view>
</template>
<script>
// 引入 child 组件
import child from './child.vue'
export default {
components: {
child
},
data() {
return {
component1: null as ComponentPublicInstance | null // 手动引入组件时的类型
}
}
}
</script>
```
#### 手动引入组件的类型规范 @manual-import-component-type
类型为：ComponentPublicInstance
## 使用及通信 @use-and-communication
### 页面与页面通信 @page-page-communication
1. 使用 [navigateTo](https://doc.dcloud.net.cn/uni-app-x/api/navigator.html#navigateto) 在 `url` 地址中携带参数
2. 使用 [event-bus](https://doc.dcloud.net.cn/uni-app-x/api/event-bus.html)
### 页面与组件通信 @page-component-communication
#### 向组件传递 `props` @transfer-component-props
示例 [详情](<!-- VUEJSON.E_component-instance.props_props-options.gitUrl -->)
::: warning 注意
- 选项式 API：`this.$props` 是 `Map` 类型，需要使用 `this.$props["propName"]` 来访问
- 组合式 API：可以使用 `.` 点操作符来访问
:::
::: preview <!-- VUEJSON.E_component-instance.props_props-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.props_props-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.props_props-composition.code -->
:::
#### 向组件传递回调函数 @transfer-component-method
示例 [详情](<!-- VUEJSON.E_component-instance.emit-function_emit-function-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.emit-function_emit-function-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.emit-function_emit-function-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.emit-function_emit-function-composition.code -->
:::
#### 使用 `provide/inject` 来向下传递参数 @provide-inject
示例 [详情](<!-- VUEJSON.E_component-instance.provide_provide-options-1.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.provide_provide-options-1.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.provide_provide-options-1.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.provide_provide-composition.code -->
:::
#### 使用 [全局变量与状态管理](../tutorial/store.md) @global-store
> store/index.uts [文件详情](https://gitcode.net/dcloud/hello-uvue/-/blob/alpha/store/index.uts)
示例 [详情](<!-- VUEJSON.E_examples.nested-component-communication_nested-component-communication-options.gitUrl -->)
::: preview <!-- VUEJSON.E_examples.nested-component-communication_nested-component-communication-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_examples.nested-component-communication_nested-component-communication-options.code -->
> 组合式 API
<!-- VUEJSON.E_examples.nested-component-communication_nested-component-communication-composition.code -->
:::
#### 在 `main.uts` 中使用 `app.config.globalProperties`
如在 `main.uts` 中的 `createApp` 方法中使用：
```ts
app.config.globalProperties.globalPropertiesReactiveObj = reactive({
str: 'default reactive string',
num: 0,
bool: false,
} as UTSJSONObject)
```
示例 [详情](<!-- VUEJSON.E_app-instance.globalProperties_globalProperties-options.gitUrl -->)
::: preview <!-- VUEJSON.E_app-instance.globalProperties_globalProperties-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_app-instance.globalProperties_globalProperties-options.code -->
> 组合式 API
<!-- VUEJSON.E_app-instance.globalProperties_globalProperties-composition.code -->
:::
### 父组件与子组件通信 @parent-child-communication
上述 [页面与组件通信](#page-component-communication) 方法同样适用于父组件与子组件通信。
### 页面调用组件方法 @page-call-component-method
#### 调用 `easycom` 组件方法 @call-easycom-component-method
> 在调用组件方法的时候如报错 `error: Reference has a nullable type` 则需要使用 `?.` 操作符（如：a?.b?.()）。
easycom组件，用法和内置组件一样。也是使用 `this.$refs` 获取组件并转换为组件的类型，通过 `.`操作符 调用组件方法或设置属性。
**语法**
```(this.$refs['组件ref属性值'] as 驼峰ComponentPublicInstance)?.foo?.();```
示例 [详情](<!-- VUEJSON.E_component-instance.methods_call-method-easycom-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.methods_call-method-easycom-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.methods_call-method-easycom-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.methods_call-method-easycom-composition.code -->
:::
##### 调用 `uni_modules easycom` 组件方法 <Badge text="HBuilderX 3.97+"> @call-uni-modules-easycom-component-method
使用 `ref` 属性拿到组件实例，调用 `easycom` 组件方法时不需要使用 `$callMethod` 方法，直接使用点操作符即可 `.`
> 在调用组件方法的时候如报错 `error: Reference has a nullable type` 则需要使用 `?.` 操作符（如：a?.b?.()）。
示例 [详情](<!-- VUEJSON.E_component-instance.methods_call-method-easycom-uni-modules-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.methods_call-method-easycom-uni-modules-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.methods_call-method-easycom-uni-modules-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.methods_call-method-easycom-uni-modules-composition.code -->
:::
#### 使用 `ref` 属性搭配 `$callMethod` 方法 @call-component-method
如果不是内置组件，也不是easycom组件，那么无法使用`.`操作符了。
此时需使用 `this.$refs` 获取组件实例，然后通过 `$callMethod` 调用组件的方法。也就是把组件的方法名、参数，当做callMethod的参数来传递。此时也就没有`.`操作符那样的代码提示和校验了。
callMethod可用于所有自定义组件，包括easycom组件也可以使用，只不过easycom组件有更简单的用法。
**语法**
```(this.$refs['组件ref属性值'] as ComponentPublicInstance)?.$callMethod('方法名', ...args)```
**组件类型**
ComponentPublicInstance
示例 [详情](<!-- VUEJSON.E_component-instance.parent_parent-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.parent_parent-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.parent_parent-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.parent_parent-composition.code -->
:::
**注意：**
- App-Android 平台 `4.0` 版本开始支持 `$callMethod` 调用 `defineExpose` 导出的方法
- Web 平台、App-iOS 平台 `4.13` 版本开始支持 `$callMethod` 调用 `defineExpose` 导出的方法
#### 内置组件的方法调用或设置属性 <Badge text="HBuilderX 3.93+"> @call-builtin-component-method
使用 `this.$refs` 获取组件并as转换为组件对应的element类型，通过 `.`操作符 调用组件方法或设置属性。
**语法**
```(this.$refs['组件ref属性值'] as Uni[xxx]Element)?.foo?.();```
**内置组件的element类型规范**
Uni`组件名(驼峰)`Element
如：
`<button>`: UniButtonElement
`<picker-view>`: UniPickerViewElement
示例 [详情](<!-- VUEJSON.E_component-instance.methods_call-method-uni-element-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.methods_call-method-uni-element-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.methods_call-method-uni-element-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.methods_call-method-uni-element-composition.code -->
:::
**bug&tips**
- 目前uts组件，即封装原生ui给uni-app或uni-app x的页面中使用，类型与内置组件的 Uni`组件名(驼峰)`Element 方式相同。目前没有代码提示。
## 组件的生命周期 @component-lifecycle
> 选项式 API 和 组件式 API 的组件生命周期使用时有所不同
>
> 比如选项式 API 中的 `onShow`、`onHide` 生命周期在组合式 API 中分别对应 `onPageShow`、`onPageHide`（在组合式 API 时会和 App 的生命周期冲突）
>
> 具体请查看 [组件生命周期](../page.md#lifecycle)
示例 [详情](<!-- VUEJSON.E_lifecycle.component_ChildComponentOptions.gitUrl -->)
::: preview <!-- VUEJSON.E_lifecycle.component_component-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_lifecycle.component_ChildComponentOptions.code -->
> 组合式 API
<!-- VUEJSON.E_lifecycle.component_ChildComponentComposition.code -->
:::
## props
- 支持[对象方式](https://cn.vuejs.org/guide/components/props.html#props-declaration)声明。从 4.0+ 支持字符串数组方式声明。使用字符串数组方式声明时，所有 prop 类型均为 any | null。
- 仅支持直接在 `export default` 内部声明，不支持其他位置定义后，在 `export default` 中引用。
- 复杂数据类型需要通过 `PropType` 标记类型，[详见](https://cn.vuejs.org/guide/typescript/options-api.html#typing-component-props)。
- `type` 不支持使用自定义的构造函数。
示例 [详情](<!-- VUEJSON.E_component-instance.props_props-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.props_props-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.props_props-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.props_props-composition.code -->
:::
## ref
在 `uni-app js 引擎版`中，非 `Web端` 只能用于获取自定义组件，不能用于获取内置组件实例（如：`view`、`text`）。\
在 `uni-app x` 中，内置组件会返回组件根节点的引用，自定义组件会返回组件实例。
**注意事项：**
- 如果多个节点或自定义组件绑定相同 `ref` 属性，将获取到最后一个节点或组件实例的引用。
- 在 `v-for` 循环时，绑定 `ref` 属性会获取到节点或组件实例的集合。
- 在 `uni-app x` 中，要访问 `$refs` 中的属性，需要使用索引方式。
示例 [详情](<!-- VUEJSON.E_component-instance.refs_refs-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.refs_refs-options.webUrl -->
> uni-app x（选项式）
<!-- VUEJSON.E_component-instance.refs_refs-options.code -->
> uni-app x（组合式）
<!-- VUEJSON.E_component-instance.refs_refs-composition.code -->
> uni-app js 引擎版
```vue
<template>
<view>
<text ref="textRef">text node</text>
<Foo ref="fooRef" />
</view>
</template>
<script lang="ts">
import type { ComponentPublicInstance } from 'vue'
export default {
onReady() {
const text = this.$refs.textRef as Element // 仅H5端支持
const foo = this.$refs.fooRef as ComponentPublicInstance
}
}
</script>
```
:::
## 自定义组件 v-model 绑定复杂表达式 @v-model-complex-expression
自定义组件 `v-model` 绑定复杂表达式时，需要通过 `as` 指定类型(仅App-Android 平台)。
::: preview
> 选项式 API
```ts
<template>
<input v-model="obj.str as string" />
</template>
<script lang="uts">
type Obj = {
str : string
}
export default {
data() {
return {
obj: {
str: "str"
} as Obj
}
}
}
</script>
```
> 组合式 API
```ts
<template>
<input v-model="obj.str as string" />
</template>
<script setup lang="uts">
type Obj = {
str: string
}
const obj = reactive({
str: "str"
} as Obj)
</script>
```
:::
## 作用域插槽的类型 @scoped-slot-type
示例 [详情](<!-- VUEJSON.E_built-in.special-elements_slots_child-options.gitUrl -->)
作用域插槽需在组件中指定插槽数据类型
::: preview <!-- VUEJSON.E_built-in.special-elements_slots_child-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_built-in.special-elements_slots_child-options.code -->
> 组合式 API
<!-- VUEJSON.E_built-in.special-elements_slots_child-composition.code -->
:::
## 递归组件
实现递归组件时不要使用组件 import 自身的写法，直接在模板内使用组件名即可。
```vue
// component-a.uvue
<template>
<view>
<text>component-a::{{text}}</text>
<component-a v-if="!end" :text="text" :limit="limit-1"></component-a>
</view>
</template>
<script>
// import componentA from './component-a' // 错误用法
export default {
name: "component-a",
props: {
text: {
type: String,
default: ''
},
limit: {
type: Number,
default: 2
}
},
computed: {
end() : boolean {
return this.limit <= 0
}
}
}
</script>
```
docs/vue/composition-api.md 0 → 100644
浏览文件 @ 629925bb
# 组合式 API
::: warning 注意
- 暂不支持 `<script setup>` 和 `<script>` 同时使用，如果需要配置 `options` 内容，比如 `name`，可以使用 `defineOptions`。
- 暂不支持顶层 `await`。
- 暂不支持 `<script setup>` 配置 `generic` 泛型类型参数。
- `App.uvue` 暂不支持组合式 API。
:::
## 响应式: 核心
<!-- VUEJSON.reactivity_core.compatibility -->
### 示例代码 @example
#### ref
接受一个内部值，返回一个响应式的、可更改的 ref 对象，此对象只有一个指向其内部值的属性 `.value`。
示例 [详情](<!-- VUEJSON.E_reactivity.core_ref_ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_ref_ref.webUrl -->
<!-- VUEJSON.E_reactivity.core_ref_ref.code -->
:::
- 使用 `<template ref>`
示例 [详情](<!-- VUEJSON.E_component-instance.refs_refs-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.refs_refs-composition.webUrl -->
<!-- VUEJSON.E_component-instance.refs_refs-composition.code -->
:::
#### watch
侦听一个或多个响应式数据源，并在数据源变化时调用所给的回调函数。
示例 [详情](<!-- VUEJSON.E_reactivity.core_watch_watch-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_watch_watch-composition.webUrl -->
<!-- VUEJSON.E_reactivity.core_watch_watch-composition.code -->
:::
#### computed
接受一个 getter 函数，返回一个只读的响应式 [ref](#ref) 对象。该 ref 通过 `.value` 暴露 getter 函数的返回值。它也可以接受一个带有 `get` 和 `set` 函数的对象来创建一个可写的 ref 对象。
::: warning 注意
- `computed()` 需通过泛型指定返回值类型。
```ts
const count = ref(0)
const doubleCount = computed<number>(() : number => {
return count.value * 2
})
```
:::
示例 [详情](<!-- VUEJSON.E_reactivity.core_computed_computed-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_computed_computed-composition.webUrl -->
<!-- VUEJSON.E_reactivity.core_computed_computed-composition.code -->
:::
#### reactive
返回一个对象的响应式代理。
- 详细信息
响应式转换是“深层”的：它会影响到所有嵌套的属性。一个响应式对象也将深层地解包任何 [ref](#ref) 属性，同时保持响应性。
若要避免深层响应式转换，只想保留对这个对象顶层次访问的响应性，请使用 [shallowReactive()](#shallowreactive) 作替代。
- 示例 [详情](<!-- VUEJSON.E_reactivity.core_reactive_reactive.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_reactive_reactive.webUrl -->
<!-- VUEJSON.E_reactivity.core_reactive_reactive.code -->
:::
#### readonly
接受一个对象 (不论是响应式还是普通的) 或是一个 [ref](#ref)，返回一个原值的只读代理。
- 详细信息
只读代理是深层的：对任何嵌套属性的访问都将是只读的。它的 [ref](#ref) 解包行为与 `reactive()` 相同，但解包得到的值是只读的。
要避免深层级的转换行为，请使用 [shallowReadonly()](#shallowreadonly) 作替代。
示例 [详情](<!-- VUEJSON.E_reactivity.core_readonly_readonly.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_readonly_readonly.webUrl -->
<!-- VUEJSON.E_reactivity.core_readonly_readonly.code -->
:::
#### watchEffect
立即运行一个函数，同时响应式地追踪其依赖，并在依赖更改时重新执行。
- 详细信息
第一个参数就是要运行的副作用函数。这个副作用函数的参数也是一个函数，用来注册清理回调。清理回调会在该副作用下一次执行前被调用，可以用来清理无效的副作用，例如等待中的异步请求 (参见下面的示例)。
第二个参数是一个可选的选项，可以用来调整副作用的刷新时机或调试副作用的依赖。
默认情况下，侦听器将在组件渲染之前执行。设置 `flush: 'post'` 将会使侦听器延迟到组件渲染之后再执行。在某些特殊情况下 (例如要使缓存失效)，可能有必要在响应式依赖发生改变时立即触发侦听器。这可以通过设置 `flush: 'sync'` 来实现。然而，该设置应谨慎使用，因为如果有多个属性同时更新，这将导致一些性能和数据一致性的问题。
返回值是一个用来停止该副作用的函数。
示例 [详情](<!-- VUEJSON.E_reactivity.core_watch-effect_watch-effect.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_watch-effect_watch-effect.webUrl -->
<!-- VUEJSON.E_reactivity.core_watch-effect_watch-effect.code -->
:::
#### watchPostEffect
[watchEffect()](#watcheffect) 使用 `flush: 'post'` 选项时的别名。
示例 [详情](<!-- VUEJSON.E_reactivity.core_watch-post-effect_watch-post-effect.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_watch-post-effect_watch-post-effect.webUrl -->
<!-- VUEJSON.E_reactivity.core_watch-post-effect_watch-post-effect.code -->
:::
#### watchSyncEffect
[watchEffect()](#watcheffect) 使用 `flush: 'sync'` 选项时的别名。
示例 [详情](<!-- VUEJSON.E_reactivity.core_watch-sync-effect_watch-sync-effect.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_watch-sync-effect_watch-sync-effect.webUrl -->
<!-- VUEJSON.E_reactivity.core_watch-sync-effect_watch-sync-effect.code -->
:::
## 响应式: 工具
<!-- VUEJSON.reactivity_utilities.compatibility -->
<!-- VUEJSON.reactivity_utilities.example -->
::: warning 注意
- `toRefs()` 仅支持 `Array` 和 `UTSJSONObject`, 不支持自定义类型。
:::
### 示例代码 @example
#### isRef
检查某个值是否为 ref。
示例 [详情](<!-- VUEJSON.E_reactivity.utilities_is-ref_is-ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.utilities_is-ref_is-ref.webUrl -->
<!-- VUEJSON.E_reactivity.utilities_is-ref_is-ref.code -->
:::
#### unref
如果参数是 ref，则返回内部值，否则返回参数本身。这是 `val = isRef(val) ? val.value : val` 计算的一个语法糖。
示例 [详情](<!-- VUEJSON.E_reactivity.utilities_un-ref_un-ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.utilities_un-ref_un-ref.webUrl -->
<!-- VUEJSON.E_reactivity.utilities_un-ref_un-ref.code -->
:::
#### toRef
可以将值、refs 或 getters 规范化为 refs。
也可以基于响应式对象上的一个属性，创建一个对应的 ref。这样创建的 ref 与其源属性保持同步：改变源属性的值将更新 ref 的值，反之亦然。
示例 [详情](<!-- VUEJSON.E_reactivity.utilities_to-ref_to-ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.utilities_to-ref_to-ref.webUrl -->
<!-- VUEJSON.E_reactivity.utilities_to-ref_to-ref.code -->
:::
#### toValue
将值、refs 或 getters 规范化为值。这与 [unref()](#unref) 类似，不同的是此函数也会规范化 getter 函数。如果参数是一个 getter，它将会被调用并且返回它的返回值。
示例 [详情](<!-- VUEJSON.E_reactivity.utilities_to-value_to-value.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.utilities_to-value_to-value.webUrl -->
<!-- VUEJSON.E_reactivity.utilities_to-value_to-value.code -->
:::
#### toRefs
将一个响应式对象转换为一个普通对象，这个普通对象的每个属性都是指向源对象相应属性的 ref。每个单独的 ref 都是使用 [toRef()](#toref) 创建的。
示例 [详情](<!-- VUEJSON.E_reactivity.utilities_to-refs_to-refs.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.utilities_to-refs_to-refs.webUrl -->
<!-- VUEJSON.E_reactivity.utilities_to-refs_to-refs.code -->
:::
#### isProxy
检查一个对象是否是由 [reactive()](#reactive)、[readonly()](#readonly)、[shallowReactive()](#shallowreactive) 或 [shallowReadonly()](#shallowreadonly) 创建的代理。
示例 [详情](<!-- VUEJSON.E_reactivity.utilities_is-proxy_is-proxy.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.utilities_is-proxy_is-proxy.webUrl -->
<!-- VUEJSON.E_reactivity.utilities_is-proxy_is-proxy.code -->
:::
#### isReactive
检查一个对象是否是由 [reactive()](#reactive) 或 [shallowReactive()](#shallowreactive) 创建的代理。
示例 [详情](<!-- VUEJSON.E_reactivity.utilities_is-reactive_is-reactive.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.utilities_is-reactive_is-reactive.webUrl -->
<!-- VUEJSON.E_reactivity.utilities_is-reactive_is-reactive.code -->
:::
#### isReadonly
检查传入的值是否为只读对象。只读对象的属性可以更改，但他们不能通过传入的对象直接赋值。
通过 [readonly()](#readonly) 和 [shallowReadonly()](#shallowreadonly) 创建的代理都是只读的，因为他们是没有 set 函数的 [computed()](#computed) ref。
示例 [详情](<!-- VUEJSON.E_reactivity.utilities_is-readonly_is-readonly.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.utilities_is-readonly_is-readonly.webUrl -->
<!-- VUEJSON.E_reactivity.utilities_is-readonly_is-readonly.code -->
:::
## 响应式: 进阶
<!-- VUEJSON.reactivity_advanced.compatibility -->
<!-- VUEJSON.reactivity_advanced.example -->
### 示例代码 @example
#### customRef
创建一个自定义的 ref，显式声明对其依赖追踪和更新触发的控制方式。
- 详细信息
`customRef()` 预期接收一个工厂函数作为参数，这个工厂函数接受 `track` 和 `trigger` 两个函数作为参数，并返回一个带有 get 和 set 方法的对象。
一般来说，`track()` 应该在 `get()` 方法中调用，而 `trigger()` 应该在 `set()` 中调用。然而事实上，你对何时调用、是否应该调用他们有完全的控制权。
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_custom-ref_custom-ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_custom-ref_custom-ref.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_custom-ref_custom-ref.code -->
:::
#### effectScope
创建一个 effect 作用域，可以捕获其中所创建的响应式副作用 (即计算属性和侦听器)，这样捕获到的副作用可以一起处理。对于该 API 的使用细节
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_effect-scope_effect-scope.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_effect-scope_effect-scope.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_effect-scope_effect-scope.code -->
:::
#### getCurrentScope
如果有的话，返回当前活跃的 effect 作用域。
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_get-current-scope_get-current-scope.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_get-current-scope_get-current-scope.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_get-current-scope_get-current-scope.code -->
:::
#### onScopeDispose
在当前活跃的 effect 作用域上注册一个处理回调函数。当相关的 effect 作用域停止时会调用这个回调函数。
这个方法可以作为可复用的组合式函数中 `onUnmounted` 的替代品，它并不与组件耦合，因为每一个 Vue 组件的 `setup()` 函数也是在一个 effect 作用域中调用的。
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_on-scope-dispose_on-scope-dispose.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_on-scope-dispose_on-scope-dispose.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_on-scope-dispose_on-scope-dispose.code -->
:::
#### shallowReactive
[reactive()](#reactive) 的浅层作用形式。
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_shallow-reactive_shallow-reactive.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_shallow-reactive_shallow-reactive.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_shallow-reactive_shallow-reactive.code -->
:::
#### shallowReadonly
[readonly()](#readonly) 的浅层作用形式
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_shallow-readonly_shallow-readonly.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_shallow-readonly_shallow-readonly.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_shallow-readonly_shallow-readonly.code -->
:::
#### shallowRef
[ref()](#ref) 的浅层作用形式。
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_shallow-ref_shallow-ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_shallow-ref_shallow-ref.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_shallow-ref_shallow-ref.code -->
:::
#### toRaw
根据一个 Vue 创建的代理返回其原始对象。
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_to-raw_to-raw.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_to-raw_to-raw.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_to-raw_to-raw.code -->
:::
#### triggerRef
强制触发依赖于一个[浅层 ref](#shallowref) 的副作用，这通常在对浅引用的内部值进行深度变更后使用。
示例 [详情](<!-- VUEJSON.E_reactivity.advanced_trigger-ref_trigger-ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.advanced_trigger-ref_trigger-ref.webUrl -->
<!-- VUEJSON.E_reactivity.advanced_trigger-ref_trigger-ref.code -->
:::
## 生命周期钩子 @page-lifecycle
<!-- VUEJSON.composition_lifecycle.compatibility -->
示例 [详情](<!-- VUEJSON.E_lifecycle.page_page-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_lifecycle.page_page-composition.webUrl -->
<!-- VUEJSON.E_lifecycle.page_page-composition.code -->
:::
[页面及组件生命周期流程图](../page.md#lifecycleflow)
## \<script setup> @script_setup
### 基本语法 @basic-syntax
- 仅支持 `export default {}` 方式定义组件。
- `data` 仅支持函数返回对象字面量方式。
```ts
<script lang="uts">
export default {
data() {
return {
// 必须写这里
}
}
}
</script>
```
<!-- VUEJSON.script.description -->
<!-- VUEJSON.script.attribute -->
<!-- VUEJSON.script.event -->
<!-- VUEJSON.script.example -->
<!-- VUEJSON.script.compatibility -->
<!-- VUEJSON.script.children -->
<!-- VUEJSON.script.reference -->
### 示例 @example
示例 [详情](<!-- VUEJSON.E_component-instance.setup-function_setup-function.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.setup-function_setup-function.webUrl -->
<!-- VUEJSON.E_component-instance.setup-function_setup-function.code -->
:::
## 单文件组件中方法兼容性 @single-file-component-script-methods
<!-- VUEJSON.single_file_component_script.compatibility -->
### defineProps()
仅支持数组字面量、对象字面量定义（等同于 `options` 中的 `props`规则）及使用纯类型参数的方式来声明。
#### 示例
[详情](<!-- VUEJSON.E_component-instance.props_props-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.props_props-composition.webUrl -->
<!-- VUEJSON.E_component-instance.props_props-composition.code -->
:::
### defineEmits()
仅支持数组字面量和纯类型参数的方式来声明。
```ts
// 数组字面量
const emit = defineEmits(['change'])
// 纯类型参数
const emit = defineEmits<{
(e : 'change', id : number) : void
}>()
const emit = defineEmits<{
// 具名元组语法
change : [id: number]
}>()
```
#### 示例
[详情](<!-- VUEJSON.E_component-instance.emit-function_emit-function-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.emit-function_emit-function-composition.webUrl -->
<!-- VUEJSON.E_component-instance.emit-function_child-composition.code -->
:::
### defineOptions()
仅支持对象字面量方式定义。
```ts
defineOptions({
data() {
return {
count: 0,
price: 10,
total: 0
}
},
computed: {
doubleCount() : number {
return this.count * 2
},
},
watch: {
count() {
this.total = this.price * this.count
},
},
methods: {
increment() {
this.count++
}
}
})
```
#### 示例
[详情](<!-- VUEJSON.E_component-instance.options_options-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.options_options-composition.webUrl -->
<!-- VUEJSON.E_component-instance.options_options-composition.code -->
:::
### defineExpose()
使用 `<script setup>` 的组件是默认关闭的——即通过模板引用或者 $parent 链获取到的组件的公开实例，不会暴露任何在 `<script setup>` 中声明的绑定。
可以通过 `defineExpose` 编译器宏来显式指定在 `<script setup>` 组件中要暴露出去的属性：
仅支持对象字面量方式定义，导出的变量或方法，必须是 `setup` 中定义的，暂不支持外部定义。
示例 [详情](<!-- VUEJSON.E_component-instance.data_data-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.data_data-composition.webUrl -->
<!-- VUEJSON.E_component-instance.data_data-composition.code -->
:::
### defineModel()
这个宏可以用来声明一个双向绑定 prop，通过父组件的 `v-model` 来使用。组件 [v-model](./built-in.md#v-model) 指南中也讨论了示例用法。
在底层，这个宏声明了一个 model prop 和一个相应的值更新事件。如果第一个参数是一个字符串字面量，它将被用作 prop 名称；否则，prop 名称将默认为 `"modelValue"`。在这两种情况下，你都可以再传递一个额外的对象，它可以包含 prop 的选项和 model ref 的值转换选项。
#### 示例
[详情](<!-- VUEJSON.E_directive.v-model_Foo-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-model_v-model-composition.webUrl -->
<!-- VUEJSON.E_directive.v-model_Foo-composition.code -->
:::
### defineSlots()
这个宏可以用于为 IDE 提供插槽名称和 props 类型检查的类型提示。
`defineSlots()` 只接受类型参数，没有运行时参数。类型参数应该是一个类型字面量，其中属性键是插槽名称，值类型是插槽函数。函数的第一个参数是插槽期望接收的 props，其类型将用于模板中的插槽 props。返回类型目前被忽略，可以是 `any`，但我们将来可能会利用它来检查插槽内容。
它还返回 `slots` 对象，该对象等同于在 setup 上下文中暴露或由 `useSlots()` 返回的 `slots` 对象。
#### 示例
[详情](<!-- VUEJSON.E_directive.v-slot_Foo-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-slot_v-slot-composition.webUrl -->
<!-- VUEJSON.E_directive.v-slot_Foo-composition.code -->
:::
### useSlots() 和 useAttrs()
在 `<script setup>` 使用 `slots` 和 `attrs` 的情况应该是相对来说较为罕见的，因为可以在模板中直接通过 `$slots` 和 `$attrs` 来访问它们。在你的确需要使用它们的罕见场景中，可以分别用 `useSlots` 和 `useAttrs` 两个辅助函数：
#### useSlots() 示例 @useslots-example
[详情](<!-- VUEJSON.E_directive.v-slot_v-slot-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-slot_v-slot-composition.webUrl -->
<!-- VUEJSON.E_directive.v-slot_v-slot-composition.code -->
:::
#### useAttrs() 示例 @useattrs-example
[详情](<!-- VUEJSON.E_component-instance.attrs_child-composition.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.attrs_attrs-composition.webUrl -->
<!-- VUEJSON.E_component-instance.attrs_child-composition.code -->
:::
docs/vue/data-bind.md 0 → 100644
浏览文件 @ 629925bb
# 数据绑定模型
## 声明响应式状态 @declaring-reactive-state
### 选项式 API @options-api
选用选项式 API 时，会用 `data` 选项来声明组件的响应式状态。此选项的值应为返回一个对象的函数。Vue 将在创建新组件实例的时候调用此函数，并将函数返回的对象用响应式系统进行包装。此对象的所有顶层属性都会被代理到组件实例 (即方法和生命周期钩子中的 `this`) 上。
示例 [详情](<!-- VUEJSON.E_component-instance.data_data-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.data_data-options.webUrl -->
<!-- VUEJSON.E_component-instance.data_data-options.code -->
:::
### 组合式 API @composition-api
选用组合式 API 时，会用 `ref`、`reactive` 来声明组件的响应式状态。
#### ref
在组合式 API 中，推荐使用 `ref()` 函数来声明响应式状态。需要给 `ref` 标注类型，如：`ref<string>()`
`ref()` 接收参数，并将其包裹在一个带有 `.value` 属性的 `ref` 对象中返回
**注意**：在模板中使用 ref 时，我们不需要附加 `.value`（为了方便起见，当在模板中使用时，ref 会自动解包）。
示例 [详情](<!-- VUEJSON.E_reactivity.core_ref_ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_ref_ref.webUrl -->
<!-- VUEJSON.E_reactivity.core_ref_ref.code -->
:::
#### reactive
还有另一种声明响应式状态的方式，即使用 reactive() API。与将内部值包装在特殊对象中的 ref 不同，reactive() 将使对象本身具有响应性，还可以使用 `readOnly` 来禁止修改
值得注意的是，reactive() 返回的是一个原始对象的 Proxy，它和原始对象是不相等的
只有代理对象是响应式的，更改原始对象不会触发更新。因此，使用 Vue 的响应式系统的最佳实践是仅使用你声明对象的代理版本。
示例 [详情](<!-- VUEJSON.E_reactivity.core_readonly_readonly.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_readonly_readonly.webUrl -->
<!-- VUEJSON.E_reactivity.core_readonly_readonly.code -->
:::
#### defineExpose
使用 `<script setup>` 的组件是**默认关闭**的——即通过模板引用或者 `$parent` 链获取到的组件的公开实例，**不会**暴露任何在 `<script setup>` 中声明的绑定。
可以通过 `defineExpose` 编译器宏来显式指定在 `<script setup>` 组件中要暴露出去的属性：
> 在示例中，使用 `defineExpose` 导出一个方法供自动化测试使用
示例 [详情](<!-- VUEJSON.E_component-instance.define-expose_define-expose.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.define-expose_define-expose.webUrl -->
<!-- VUEJSON.E_component-instance.define-expose_define-expose.code -->
:::
## 绑定变量 @bind-data
### 在模板里绑定 @bind-template-data
当使用 `Options API` `data` 或 `Composition API` 的 `ref` 、 `reactive` 定义了响应式数据后，可以在模板中使用 `{{}}` 语法绑定数据
可以在模板中使用以下任一指令一起：
- `v-bind` 或 `:`（简写）
- `v-if`、`v-else-if` 或 `v-else`
- `v-for`
示例 [详情](<!-- VUEJSON.E_built-in.special-elements_template_template-options.gitUrl -->)
::: preview <!-- VUEJSON.E_built-in.special-elements_template_template-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_built-in.special-elements_template_template-options.code -->
> 组合式 API
<!-- VUEJSON.E_built-in.special-elements_template_template-composition.code -->
:::
### 在样式里绑定 @v-bind-css-data
|App|Web|
|:-:|:-:|
|x |4.13+ |
单文件组件的 `<style>` 标签支持使用 `v-bind` CSS 函数将 CSS 的值链接到动态的组件状态
这个语法同样也适用于 `<script setup>`，且支持 UTS 表达式 (需要用引号包裹起来)
`v-bind` 也可在样式中使用，可以很方便的在 uts 中改变样式，如下所示：
示例 [详情](<!-- VUEJSON.E_directive.v-bind_v-bind-options.gitUrl -->)
::: preview <!-- VUEJSON.E_directive.v-bind_v-bind-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_directive.v-bind_v-bind-options.code -->
> 组合式 API
<!-- VUEJSON.E_directive.v-bind_v-bind-composition.code -->
:::
## 定义方法 @methods
使用选项式 API 时可以在 `methods` 选项中定义方法，这些方法可以在模板中使用\
而使用组合式 API 时，可以直接在 `<script setup lang="uts">` 中定义方法
定义方法之后，可以传递给子组件，子组件使用 `emit` 调用，也可以在 `script` 中直接使用
示例 [详情](<!-- VUEJSON.E_reactivity.core_ref_ref.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_ref_ref.webUrl -->
<!-- VUEJSON.E_reactivity.core_ref_ref.code -->
:::
docs/vue/global-api.md 0 → 100644
浏览文件 @ 629925bb
# 全局 API
## 应用实例 @app-instance
### 兼容性 @compatibility
<!-- VUEJSON.application.compatibility -->
### app.use
`app.use` 支持通过对象字面量、函数及 `definePlugin` 方式定义插件。
支持传递插件参数，当传递插件参数时，`app` 的类型需要指定为 `VueApp`。
示例 [详情](<!-- VUEJSON.E_app-instance.use_use-options.gitUrl -->)
::: preview <!-- VUEJSON.E_app-instance.use_use-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_app-instance.use_use-options.code -->
> 组合式 API
<!-- VUEJSON.E_app-instance.use_use-composition.code -->
:::
### app.config.globalProperties
请注意，`globalProperties` 是一个保留关键字，因此在项目中请勿声明名为 `globalProperties` 的变量。
在向 `globalProperties` 注册方法时，请使用直接函数表达式方式进行赋值。不支持先声明函数，再将其注册到 `globalProperties` 上的方式。同时，注册的函数一旦被赋值，不允许进行修改。
`globalProperties` 在编译时处理，因此确保你的操作在编译时是可知的。例如，将变量赋值给 `globalProperties` 时，这个变量在编译时必须是已知的，而不能是在运行时才能确定的变量。
件参数，当传递插件参数时，`app` 的类型需要指定为 `VueApp`。
示例 [详情](<!-- VUEJSON.E_app-instance.globalProperties_globalProperties-options.gitUrl -->)
::: preview <!-- VUEJSON.E_app-instance.globalProperties_globalProperties-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_app-instance.globalProperties_globalProperties-options.code -->
> 组合式 API
<!-- VUEJSON.E_app-instance.globalProperties_globalProperties-composition.code -->
:::
## 应用生命周期 @app-lifecycle
uni-app x 新增了 [onLastPageBackPress](../collocation/App.md#applifecycle) 和 [onExit](../collocation/App.md#applifecycle) 应用级生命周期，Android退出应用逻辑写在app.uvue里，新建项目的模板自动包含相关代码。如需修改退出逻辑，请直接修改相关代码。
示例 [详情](<!-- VUEJSON.E_App.example.gitUrl -->)
::: preview <!-- VUEJSON.E_App.example.webUrl -->
<!-- VUEJSON.E_App.example.code -->
:::
## 通用 @general
<!-- VUEJSON.general.compatibility -->
<!-- VUEJSON.general.example -->
### nextTick 使用注意事项 @nexttick
目前 nextTick 可以保证当前数据已经同步到 DOM，但是由于排版和渲染是异步的的，所以 nextTick 不能保证 DOM 排版以及渲染完毕。如果需要获取排版后的节点信息推荐使用 [uni.createSelectorQuery](../api/nodes-info.md) 不推荐直接使用 [Element](../dom/element.md) 对象。在修改 DOM 后，立刻使用 [Element](../dom/element.md) 对象的同步接口获取 DOM 状态可能获取到的是排版之前的，而 [uni.createSelectorQuery](../api/nodes-info.md) 可以保障获取到的节点信息是排版之后的。
docs/vue/modifier.md 0 → 100644
浏览文件 @ 629925bb
## 事件修饰符 @modifier
### stop
<!-- VUEJSON.eventModifiers.stop.description -->
<!-- VUEJSON.eventModifiers.stop.compatibility -->
### prevent
<!-- VUEJSON.eventModifiers.prevent.description -->
<!-- VUEJSON.eventModifiers.prevent.compatibility -->
### capture
<!-- VUEJSON.eventModifiers.capture.description -->
<!-- VUEJSON.eventModifiers.capture.compatibility -->
### self
<!-- VUEJSON.eventModifiers.self.description -->
<!-- VUEJSON.eventModifiers.self.compatibility -->
### once
<!-- VUEJSON.eventModifiers.once.description -->
<!-- VUEJSON.eventModifiers.once.compatibility -->
### passive
<!-- VUEJSON.eventModifiers.passive.description -->
<!-- VUEJSON.eventModifiers.passive.compatibility -->
## 按键修饰符
### enter
<!-- VUEJSON.keyModifiers.enter.description -->
<!-- VUEJSON.keyModifiers.enter.compatibility -->
### tab
<!-- VUEJSON.keyModifiers.tab.description -->
<!-- VUEJSON.keyModifiers.tab.compatibility -->
### delete
<!-- VUEJSON.keyModifiers.delete.description -->
<!-- VUEJSON.keyModifiers.delete.compatibility -->
### esc
<!-- VUEJSON.keyModifiers.esc.description -->
<!-- VUEJSON.keyModifiers.esc.compatibility -->
### space
<!-- VUEJSON.keyModifiers.space.description -->
<!-- VUEJSON.keyModifiers.space.compatibility -->
### up
<!-- VUEJSON.keyModifiers.up.description -->
<!-- VUEJSON.keyModifiers.up.compatibility -->
### down
<!-- VUEJSON.keyModifiers.down.description -->
<!-- VUEJSON.keyModifiers.down.compatibility -->
### left
<!-- VUEJSON.keyModifiers.left.description -->
<!-- VUEJSON.keyModifiers.left.compatibility -->
### right
<!-- VUEJSON.keyModifiers.right.description -->
<!-- VUEJSON.keyModifiers.right.compatibility -->
## 鼠标按键修饰符
### left
<!-- VUEJSON.mouseModifiers.left.description -->
<!-- VUEJSON.mouseModifiers.left.compatibility -->
### right
<!-- VUEJSON.mouseModifiers.right.description -->
<!-- VUEJSON.mouseModifiers.right.compatibility -->
### middle
<!-- VUEJSON.mouseModifiers.middle.description -->
<!-- VUEJSON.mouseModifiers.middle.compatibility -->
## 系统按键修饰符
### ctrl
<!-- VUEJSON.systemModifiers.ctrl.description -->
<!-- VUEJSON.systemModifiers.ctrl.compatibility -->
### alt
<!-- VUEJSON.systemModifiers.alt.description -->
<!-- VUEJSON.systemModifiers.alt.compatibility -->
### shift
<!-- VUEJSON.systemModifiers.shift.description -->
<!-- VUEJSON.systemModifiers.shift.compatibility -->
### meta
<!-- VUEJSON.systemModifiers.meta.description -->
<!-- VUEJSON.systemModifiers.meta.compatibility -->
### exact
<!-- VUEJSON.systemModifiers.exact.description -->
<!-- VUEJSON.systemModifiers.exact.compatibility -->
## props 修饰符
### sync
<!-- VUEJSON.propsModifiers.sync.description -->
<!-- VUEJSON.propsModifiers.sync.compatibility -->
## v-model 修饰符
### lazy
<!-- VUEJSON.vModelModifiers.lazy.description -->
<!-- VUEJSON.vModelModifiers.lazy.compatibility -->
### number
<!-- VUEJSON.vModelModifiers.number.description -->
<!-- VUEJSON.vModelModifiers.number.compatibility -->
### trim
<!-- VUEJSON.vModelModifiers.trim.description -->
<!-- VUEJSON.vModelModifiers.trim.compatibility -->
docs/vue/options-api.md 0 → 100644
浏览文件 @ 629925bb
# 选项式 API @options-api
选项式 API，要求在script里编写`export default {}`，在其中定义data、methods、生命周期等选项。
## 状态选项
<!-- VUEJSON.options_state.compatibility -->
### 示例代码 @example
#### data
用于声明组件初始响应式状态的函数。
示例 [详情](<!-- VUEJSON.E_component-instance.data_data-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.data_data-options.webUrl -->
<!-- VUEJSON.E_component-instance.data_data-options.code -->
:::
#### props
用于声明一个组件的 props。
示例 [详情](<!-- VUEJSON.E_component-instance.props_props-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.props_props-options.webUrl -->
<!-- VUEJSON.E_component-instance.props_props-options.code -->
:::
#### computed
用于声明要在组件实例上暴露的计算属性。
示例 [详情](<!-- VUEJSON.E_reactivity.core_computed_computed-options.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_computed_computed-options.webUrl -->
<!-- VUEJSON.E_reactivity.core_computed_computed-options.code -->
:::
#### methods
用于声明要混入到组件实例中的方法。
声明的方法可以直接通过组件实例访问，或者在模板语法表达式中使用。所有的方法都会将它们的 `this` 上下文自动绑定为组件实例，即使在传递时也如此。
在声明方法时避免使用箭头函数，因为它们不能通过 `this` 访问组件实例。
[详情点击查看](./component.md#page-call-component-method)
#### watch
用于声明在数据更改时调用的侦听回调。
::: warning 注意
- `watch immediate` 第一次调用时，App-Android 平台旧值为初始值，web 平台为 null。
:::
示例 [详情](<!-- VUEJSON.E_reactivity.core_watch_watch-options.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_watch_watch-options.webUrl -->
<!-- VUEJSON.E_reactivity.core_watch_watch-options.code -->
:::
#### emits
用于声明由组件触发的自定义事件。
示例 [详情](<!-- VUEJSON.E_component-instance.emit-function_emit-function-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.emit-function_emit-function-options.webUrl -->
<!-- VUEJSON.E_component-instance.emit-function_child-options.code -->
:::
## 渲染选项 @rendering-options
<!-- VUEJSON.options_rendering.compatibility -->
### 示例代码 @example
#### template
用于声明组件的字符串模板。
示例 [详情](<!-- VUEJSON.E_built-in.special-elements_template_template-options.gitUrl -->)
::: preview <!-- VUEJSON.E_built-in.special-elements_template_template-options.webUrl -->
<!-- VUEJSON.E_built-in.special-elements_template_template-options.code -->
:::
#### render
用于编程式地创建组件虚拟 DOM 树的函数。
`render` 是字符串模板的一种替代，可以使你利用 JavaScript 的丰富表达力来完全编程式地声明组件最终的渲染输出。
预编译的模板，例如单文件组件中的模板，会在构建时被编译为 `render` 选项。如果一个组件中同时存在 `render` 和 `template，则` `render` 将具有更高的优先级。
示例 [详情](<!-- VUEJSON.E_render-function.render_render-options.gitUrl -->)
::: preview <!-- VUEJSON.E_render-function.render_render-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_render-function.render_render-options.code -->
> 组合式 API
<!-- VUEJSON.E_render-function.render_render-composition.code -->
:::
#### slots
一个在渲染函数中以编程方式使用插槽时辅助类型推断的选项。
示例 [详情](<!-- VUEJSON.E_component-instance.slots_slots-options.gitUrl -->)
作用域插槽需在组件中指定插槽数据类型
::: preview <!-- VUEJSON.E_component-instance.slots_slots-options.webUrl -->
<!-- VUEJSON.E_component-instance.slots_slots-options.code -->
:::
## 生命周期选项 @lifecycle-options
<!-- VUEJSON.options_lifecycle.compatibility -->
### mounted、unmounted 使用注意事项
目前 mounted、unmounted 可以保证当前数据已经同步到 DOM，但是由于排版和渲染是异步的的，所以 mounted、unmounted 不能保证 DOM 排版以及渲染完毕。\
如果需要获取排版后的节点信息推荐使用 [uni.createSelectorQuery](../api/nodes-info.md) 不推荐直接使用 [Element](../dom/unielement.md) 对象。\
在修改 DOM 后，立刻使用 [Element](../dom/unielement.md) 对象的同步接口获取 DOM 状态可能获取到的是排版之前的，而 [uni.createSelectorQuery](../api/nodes-info.md) 可以保障获取到的节点信息是排版之后的。
示例 [详情](<!-- VUEJSON.E_lifecycle.page_page-options.gitUrl -->)
::: preview <!-- VUEJSON.E_lifecycle.page_page-options.webUrl -->
<!-- VUEJSON.E_lifecycle.page_page-options.code -->
:::
## 组合选项 @options-composition
<!-- VUEJSON.options_composition.compatibility -->
### inject
当使用 `inject` 声明从上层提供方注入的属性时，支持两种写法：字符串数组和对象。推荐使用对象写法，因为当使用数组方法时，类型会被推导为 `any | null` 类型。\
使用对象写法时，额外增加 `type` 属性用于标记类型。如果注入的属性类型不是基础数据类型，需要通过 `PropType` 来标记类型：
示例 [详情](<!-- VUEJSON.E_component-instance.inject_inject-options-1.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.provide_provide-options-1.webUrl -->
> inject 1
<!-- VUEJSON.E_component-instance.inject_inject-options-1.code -->
> inject 2
<!-- VUEJSON.E_component-instance.inject_inject-options-2.code -->
:::
### mixins
一个包含组件选项对象的数组，这些选项都将被混入到当前组件的实例中。
`mixins` 选项接受一个 mixin 对象数组。这些 mixin 对象可以像普通的实例对象一样包含实例选项，它们将使用一定的选项合并逻辑与最终的选项进行合并。举例来说，如果你的 mixin 包含了一个 `created` 钩子，而组件自身也有一个，那么这两个函数都会被调用。
- `mixins` 仅支持通过字面量对象方式和 `defineMixin` 函数方式定义。\
```ts
const mixin1 = defineMixin({
onLoad() {
console.log('mixin1 onLoad')
}
})
export default {
mixins: [
mixin1,
{
data() {
return {
mixin2: 'mixin2'
}
}
}
]
}
```
- 同名属性会被覆盖，同名生命周期会依次执行。同名属性的优先级如下：
- 在 `app.mixin` 内嵌入的 mixin `<` 在 `app.mixin` 中声明的 mixin `<` 在 `page.mixin` 内嵌入的 mixin `<` 在 `page.mixin` 中声明的 mixin `<` 在 `component.mixin` 内嵌入的 mixin `<` 在 `component.mixin` 中声明的 mixin
- 同名生命周期的执行顺序如下：
1. 在 `app.mixin` 内嵌入的 mixin
2. 在 `app.mixin` 中声明的 mixin
3. 在 `page.mixin` 内嵌入的 mixin
4. 在 `page.mixin` 中声明的 mixin
5. 在 `component.mixin` 内嵌入的 mixin
6. 在 `component.mixin` 中声明的 mixin
::: preview <!-- VUEJSON.E_component-instance.mixins_mixins-web.webUrl -->
示例 [详情](<!-- VUEJSON.E_component-instance.mixins-app-page-namesake.gitUrl -->)
> mixins-web
<!-- VUEJSON.E_component-instance.mixins_mixins-web.code -->
> mixins-app-page-namesake
<!-- VUEJSON.E_component-instance.mixins_mixins-app-page-namesake.code -->
> mixins-app
<!-- VUEJSON.E_component-instance.mixins_mixins-app.code -->
:::
## 其他杂项
<!-- VUEJSON.options_misc.compatibility -->
<!-- VUEJSON.options_misc.example -->
### 示例代码 @example
#### name
用于显式声明组件展示时的名称。
组件的名字有以下用途：
- 在组件自己的模板中递归引用自己时
- 在 Vue 开发者工具中的组件树显示时
- 在组件抛出的警告追踪栈信息中显示时
示例 [详情](<!-- VUEJSON.E_component-instance.circular-reference_circular-reference-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.circular-reference_circular-reference-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.circular-reference_circular-reference-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.circular-reference_circular-reference-composition.code -->
:::
#### inheritAttrs
用于控制是否启用默认的组件 attribute 透传行为。
默认情况下，父组件传递的，但没有被子组件解析为 props 的 attributes 绑定会被“透传”。这意味着当我们有一个单根节点的子组件时，这些绑定会被作为一个常规的 attribute 应用在子组件的根节点元素上。当你编写的组件想要在一个目标元素或其他组件外面包一层时，可能并不期望这样的行为。我们可以通过设置 `inheritAttrs` 为 `false` 来禁用这个默认行为。这些 attributes 可以通过 `$attrs` 这个实例属性来访问，并且可以通过 `v-bind` 来显式绑定在一个非根节点的元素上。
示例 [详情](<!-- VUEJSON.E_component-instance.mixins_mixins-web.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.mixins_mixins-web.webUrl -->
> inheritAttrs: true
<!-- VUEJSON.E_component-instance.mixins_components_Comp1.code -->
> inheritAttrs: false
<!-- VUEJSON.E_component-instance.mixins_components_Comp2.code -->
:::
#### components
一个对象，用于注册对当前组件实例可用的组件。
示例 [详情](<!-- VUEJSON.E_component-instance.attrs_attrs-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.attrs_attrs-options.webUrl -->
> 选项式 API
<!-- VUEJSON.E_component-instance.attrs_attrs-options.code -->
> 组合式 API
<!-- VUEJSON.E_component-instance.attrs_attrs-composition.code -->
:::
- 参考[组件](./component.md)
## 组件实例 @component-instance
<!-- VUEJSON.component_instance.compatibility -->
### 示例代码 @example
#### $data
从 `data` 选项函数中返回的对象，会被组件赋为响应式。组件实例将会代理对其数据对象的属性访问。
##### 使用注意事项 @options-data
data内 $ 开头的属性不可直接使用 `this.$xxx`访问，需要使用 `this.$data['$xxx']` ，这是vue的规范
> 目前安卓端可以使用 this.$xxx 访问是Bug而非特性，请勿使用此特性。
示例
```vue
<template>
<view></view>
</template>
<script>
export default {
data() {
return {
$a: 1
}
},
onReady() {
console.log(this.$data['$a'] as number) // 1
}
}
</script>
```
示例 [详情](<!-- VUEJSON.E_component-instance.data_data-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.data_data-options.webUrl -->
<!-- VUEJSON.E_component-instance.data_data-options.code -->
:::
#### $props
表示组件当前已解析的 props 对象。
示例 [详情](<!-- VUEJSON.E_component-instance.props_props-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.props_props-options.webUrl -->
<!-- VUEJSON.E_component-instance.props_props-options.code -->
:::
#### $el
该组件实例管理的 DOM 根节点。
示例 [详情](<!-- VUEJSON.E_component-instance.el_el-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.el_el-options.webUrl -->
<!-- VUEJSON.E_component-instance.el_el-options.code -->
:::
#### $options
已解析的用于实例化当前组件的组件选项。
示例 [详情](<!-- VUEJSON.E_component-instance.options_options-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.options_options-options.webUrl -->
<!-- VUEJSON.E_component-instance.options_options-options.code -->
:::
#### $parent
当前组件可能存在的父组件实例，如果当前组件是顶层组件，则为 `null`。
示例 [详情](<!-- VUEJSON.E_component-instance.parent_parent-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.parent_parent-options.webUrl -->
<!-- VUEJSON.E_component-instance.parent_parent-options.code -->
:::
#### $root
当前组件树的根组件实例。如果当前实例没有父组件，那么这个值就是它自己。
示例 [详情](<!-- VUEJSON.E_component-instance.root_root-options.gitUrl -->)
::: preview
<!-- VUEJSON.E_component-instance.root_root-options.code -->
:::
#### $slots
一个表示父组件所传入插槽的对象。
示例 [详情](<!-- VUEJSON.E_component-instance.slots_slots-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.slots_slots-options.webUrl -->
<!-- VUEJSON.E_component-instance.slots_slots-options.code -->
:::
#### $refs
一个包含 DOM 元素和组件实例的对象，通过模板引用注册。
示例 [详情](<!-- VUEJSON.E_component-instance.refs_refs-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.refs_refs-options.webUrl -->
<!-- VUEJSON.E_component-instance.refs_refs-options.code -->
:::
#### $attrs
一个包含了组件所有透传 attributes 的对象。
示例 [详情](<!-- VUEJSON.E_component-instance.attrs_attrs-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.attrs_attrs-options.webUrl -->
<!-- VUEJSON.E_component-instance.attrs_attrs-options.code -->
:::
#### $watch()
用于命令式地创建侦听器的 API。
示例 [详情](<!-- VUEJSON.E_reactivity.core_watch_watch-options.gitUrl -->)
::: preview <!-- VUEJSON.E_reactivity.core_watch_watch-options.webUrl -->
<!-- VUEJSON.E_reactivity.core_watch_watch-options.code -->
:::
#### $emit()
在当前组件触发一个自定义事件。任何额外的参数都会传递给事件监听器的回调函数。
示例 [详情](<!-- VUEJSON.E_component-instance.emit-function_emit-function-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.emit-function_emit-function-options.webUrl -->
<!-- VUEJSON.E_component-instance.emit-function_emit-function-options.code -->
:::
#### $forceUpdate()
强制该组件重新渲染。
示例 [详情](<!-- VUEJSON.E_component-instance.force-update_force-update-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.force-update_force-update-options.webUrl -->
<!-- VUEJSON.E_component-instance.force-update_force-update-options.code -->
:::
#### $nextTick()
绑定在实例上的 nextTick() 函数。
##### 使用注意事项 @options-nextTick
目前 $nextTick 可以保证当前数据已经同步到 DOM，但是由于排版和渲染是异步的，所以 $nextTick 不能保证 DOM 排版以及渲染完毕。\
如果需要获取排版后的节点信息推荐使用 [uni.createSelectorQuery](../api/nodes-info.md) 不推荐直接使用 [Element](../dom/unielement.md) 对象。\
在修改 DOM 后，立刻使用 [Element](../dom/unielement.md) 对象的同步接口获取 DOM 状态可能获取到的是排版之前的，而 [uni.createSelectorQuery](../api/nodes-info.md) 可以保障获取到的节点信息是排版之后的。
示例 [详情](<!-- VUEJSON.E_component-instance.nextTick_nextTick-options.gitUrl -->)
::: preview <!-- VUEJSON.E_component-instance.nextTick_nextTick-options.webUrl -->
<!-- VUEJSON.E_component-instance.nextTick_nextTick-options.code -->
:::
docs/vue/others.md 0 → 100644
浏览文件 @ 629925bb
# vue 生态
## 插件
暂不支持vue插件，比如pinia、vuex、i18n、router。简单的状态管理可以参考文档[全局变量和状态管理](../tutorial/store.md)。
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或