From d95ca23a2faf2ac18fe978cc4e8c5f85bfb8acd1 Mon Sep 17 00:00:00 2001
From: wanganxp <wanganxp@gmail.com>
Date: Thu, 9 May 2024 06:28:02 +0800
Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=A6=82=E8=BF=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/vue/README.md      | 227 ++++++++++++++++++++++++++++++++++++++--
 docs/vue/options-api.md |   2 +
 2 files changed, 220 insertions(+), 9 deletions(-)

diff --git a/docs/vue/README.md b/docs/vue/README.md
index dab15fa0..0b0d9792 100644
--- a/docs/vue/README.md
+++ b/docs/vue/README.md
@@ -1,12 +1,218 @@
-# vue
+# uvue概述
 
-uni-app x的vue规范，按照vue3规范实现，从4.0起支持组合式写法。
+[vue.js](https://vuejs.org/) 是流行的js框架，它提供了简易的模板式写法、数据双向绑定、组件机制。
 
-本文暂时只包括兼容性表格，vue功能详情另见 [vue3概述](https://uniapp.dcloud.net.cn/tutorial/vue3-basics.html#)、[Vue3 API](https://uniapp.dcloud.net.cn/tutorial/vue3-api.html)。
+但 vue.js 并不支持web之外的其他平台，也不支持uts。
 
-uni-app x中vue的用法，有单独的示例应用：[hello uvue](https://gitcode.net/dcloud/hello-uvue)。这里都是可以跑通的使用样例代码。
+uni-app x 为vue开发者提供了跨平台的解决方案。
 
-## CSS 功能 @css
+uni-app x 中，web平台内置了vue.js，其他平台为 DCloud 参考vue规范提供的兼容实现。
+
+在 uni-app x 中，页面和组件的文件后缀名均为 `*.uvue`。u 即 uni 的意思。
+
+页面与组件均符合vue的单文件组件规范，只不过页面需要在pages.json中注册且多了一批生命周期和API。
+
+在非web平台，uvue 尽可能拉齐了vue.js的功能，但仍有些不常用的功能暂未提供，需注意查看相关文档的兼容性。同时 uvue 也新增了 [easycom](./component.md#easycom) 等技术，简化组件的使用。
+
+截止到HBuilderX 4.14版，uni-app x 兼容的vue版本为3.4。
+
+hello uvue 是非常重要的vue示例，演示了各种vue功能的应用。
+
+- 插件地址：[https://ext.dcloud.net.cn/plugin?id=15021](https://ext.dcloud.net.cn/plugin?id=15021)
+- 源码地址：[https://gitcode.net/dcloud/hello-uvue](https://gitcode.net/dcloud/hello-uvue)，注意有master和alpha分支，对应HBuilderX最新的正式版和alpha版。
+
+一个 uvue 页面/组件，有3个根节点标签：
+
+1. 模板组件区 `<template>`
+2. 脚本区 `<script>`
+3. 样式区 `<style>`
+
+一个简单的选项式页面示例：
+```vue
+<template>
+	<view class="content">
+		<button @click="buttonClick">{{title}}</button>
+	</view>
+</template>
+
+<script>
+	export default {
+		data() {
+			return {
+				title: "Hello world", // 定义绑定在页面上的data数据
+			}
+		},
+		onLoad() {
+			// 页面启动的生命周期，这里编写页面加载时的逻辑
+		},
+		methods: {
+			buttonClick: function () {
+				console.log("按钮被点了")
+			},
+		}
+	}
+</script>
+
+<style>
+	.content {
+		width: 750rpx;
+		background-color: white;
+	}
+</style>
+```
+
+## template
+
+template中文名为`模板`，它类似html的标签。但有2个区别：
+
+1. html中 `script` 和 `style` 是 html 的二级节点。但在 uvue 文件中，`template`、`script`、`style` 这3个是平级关系。
+2. html 中写的是 web 标签，但 vue 的 `template` 中写的全都是 vue 组件（包括内置基础组件、自定义uvue组件、uts原生插件组件），每个组件支持属性、事件、vue 指令，还可以绑定 vue 的 data 数据。
+
+组件，即component，是vue中非常重要的概念，或者说现代开发框架都离不开组件概念。
+
+我们知道js逻辑可以封装为函数或类库。而对于页面上可视的元素，则可以将ui、样式、逻辑一起封装为组件。详见[uvue组件规范](./component.md)
+
+在 uni-app x 中， `<view>`是最基本的视图容器组件，`<text>`则是文字组件，`<button>`是按钮组件。这些都是[内置组件](../component/README.md)
+
+一个页面或组件只能有一个template标签，template下面可以有多个二级节点，如下：
+
+```vue
+<template>
+	<view>
+		<text>标题</text>
+	</view>
+	<scroll-view>
+
+	</scroll-view>
+</template>
+```
+
+## script
+
+script中编写逻辑代码。
+
+uvue中只能有一个script标签。
+
+script标签的属性如下：
+- lang
+lang 仅支持uts，不管script的lang属性写成什么，都按uts编译。
+- setup
+setup属性声明代表script里的代码为组合式写法，如果没有setup属性则为选项式写法。
+
+### 组合式API
+组合式 API，也称 Composition API，或 setup函数。
+
+组合式提供了更灵活自由、更简洁的编程方式，通过代码而不是通过规范约定死的选项来定义data、method和生命周期。
+
+如下页面代码的逻辑是：
+
+1. 定义了一个响应式`title`，初始值是"Hello world"。
+2. 在页面中放置了一个button组件，按钮文字区使用`{{}}`模板写法，里面写响应式变量`title`，那么`title`的值就会绑定到按钮的文字区，即按钮的初始文字是"Hello world"
+3. 按钮的点击事件`@click`，指向了一个方法`buttonClick`，点击按钮即触发这个方法的执行
+4. 页面onReady生命周期中打印日志
+
+```vue
+<template>
+	<view>
+		<button @click="buttonClick">{{title}}</button>
+	</view>
+</template>
+
+<script setup>
+  let title = ref("Hello world") //定义一个响应式变量。类似于选项式的定义data
+	function buttonClick() { //方法不再需要写在method下面
+	  console.log("按钮被点了")
+	}
+	onReady(() => {
+		console.log("页面onReady触发") // 页面生命周期，编写页面加载后的逻辑
+	})
+</script>
+
+```
+
+### 选项式API
+选项式 API，也称 Option API，指在script中写`export default {}`，在其中通过多个选项的对象来定义data、method和生命周期。选项所定义的属性都会暴露在函数内部的 this 上，它会指向当前的组件实例。
+
+以下代码的逻辑与上一章节组合式API的示例相同，只是写法改成了选项式写法。
+
+```vue
+<template>
+	<view>
+		<button @click="buttonClick">{{title}}</button>
+	</view>
+</template>
+
+<script>
+	export default {
+		data() {
+			return {
+				title: "Hello world", // 定义绑定在页面上的data数据
+			}
+		},
+		onReady() {
+			console.log("页面onReady触发") // 页面生命周期，编写页面加载后的逻辑
+		},
+		methods: {
+			buttonClick: function () {
+				console.log("按钮被点了")
+			},
+		}
+	}
+</script>
+```
+
+#### `export default` 外的代码
+
+既然有写在写`export default {}`里的代码，那么就有 `export default {}` 外面的代码。
+
+写在外面一般有几种情况：
+
+1. 引入第三方 uts 模块
+2. 引入非 easycom 的组件（一般组件推荐使用[easycom](./component.md#easycom)，无需导入注册）
+3. 定义 type，对 data 进行类型定义
+4. 定义作用域更大的变量
+
+```html
+<script>
+	const TAB_OFFSET = 1; // 外层静态变量不会跟随页面关闭而回收
+	import charts from 'charts.uts'; // 导入外部js/ts模块
+	import swiperPage from 'swiper-page.uvue'; //导入非easycom的组件
+	type GroupType = {
+		id : number,
+		title : string
+	} // 在uts中，为下面data数据的 groupList 定义类型
+	export default {
+		components: {
+		    swiperPage
+		}, // 注册非easycom组件
+		data() {
+			return {
+				groupList: [
+					{ id: 1, title: "第一组" },
+					{ id: 2, title: "第二组" },
+				] as GroupType[], // 为数据groupList定义ts类型
+			}
+		},
+		onLoad() {},
+		methods: {}
+	}
+</script>
+```
+
+开发者应谨慎编写 `export default {}` 外面的代码，这里的代码有2个注意事项：
+
+1. 影响应用性能。不管写在哪个页面，这部分代码都在应用启动时执行，而不是页面加载。如果`export default {}`外的代码写的太复杂，会影响应用启动速度，占用更多内存。
+2. 不跟随组件、页面关闭而回收。在外层的静态变量不会跟随页面关闭而回收。如果必要，你需要手动处理。比如 `beforeDestroy` 或 `destroyed` 生命周期进行处理。
+
+## style（CSS功能） @css
+
+style的写法与web的css基本相同。但在App端，由于并非webview渲染，支持的css有限。[详见](../css/README.md)
+
+本章节重点讲解uvue下样式的使用注意事项。
+
+一个页面/组件允许有多个style标签。
+
+style通过lang属性，可以支持less、scss、stylus等css预处理语言。
 
 ### style 标签 @style
 
@@ -24,6 +230,13 @@ uni-app x中vue的用法，有单独的示例应用：[hello uvue](https://gitco
 
 <!-- VUEJSON.style.reference -->
 
+
+### Class 与 Style 绑定 @class-style
+
+- `uni-app x` 支持绑定  `UTSJSONObject` 和 `Map` 类型数据。
+- 在App-Android平台上 `Map` 的性能高于 `UTSJSONObject` 数据类型。从 `uni-app x 4.01` 起，Web平台也支持了 `Map` 类型绑定。
+
+如下示例中，给view组件的style和class分别绑定了2个data，就可以通过在逻辑代码里修改data而实现动态修改样式。
 ```vue
 <template>
   <view>
@@ -55,11 +268,7 @@ uni-app x中vue的用法，有单独的示例应用：[hello uvue](https://gitco
 </style>
 ```
 
-### Class 与 Style 绑定 @class-style
-
 - [参见](https://uniapp.dcloud.net.cn/tutorial/vue3-basics.html#class-%E4%B8%8E-style-%E7%BB%91%E5%AE%9A)
-- `uni-app x` 支持绑定  `UTSJSONObject` 和 `Map` 类型数据。
-- 在App-Android平台上 `Map` 的性能高于 `UTSJSONObject` 数据类型。从 `uni-app x 4.01` 起，Web平台也支持了 `Map` 类型绑定。
 
 ### 深度选择器 @scoped
 
diff --git a/docs/vue/options-api.md b/docs/vue/options-api.md
index 8834a979..7c3788ee 100644
--- a/docs/vue/options-api.md
+++ b/docs/vue/options-api.md
@@ -1,5 +1,7 @@
 # 选项式 API @options-api
 
+选项式 API，要求在script里编写`export default {}`，在其中定义data、methods、生命周期等选项。
+
 ## 状态选项
 
 <!-- VUEJSON.options_state.compatibility -->
-- 
GitLab