优化组件和vue文档

docs/component/README.md

-# uvue组件概述
+# 组件概述
 
-## 定义
+## 组件定义
 
 - 组件是视图层的基本组成单元。
-- 组件是一个单独且可复用的功能模块的封装。
+- 组件是一个单独且可复用的UI及配套功能模块的封装。
+
+我们知道js逻辑可以封装为函数或类库。而对于页面上可视的元素，则可以将ui、样式、逻辑一起封装为组件。
+
+组件涉及较多的概念，包括组件名称、开头和闭合标签、组件属性、组件属性值、组件事件、组件vue指令、组件text内容、子组件。
+
+我们先看一个简单的例子：
+```vue
+<component-name property1="value" property2="value">
+	content
+</component-name>
+```
+
+上面的代码，是一个组件，组件名为component-name，这个组件有2个属性，property1和property2，这2个属性的属性值都是"value"，组件的text内容为"content"
+
+然后我们看一个全面但有些复杂的示例，这段示例融合了组件的各种概念：
+
+```vue
+<template>
+  <view></view>
+	<view>
+		<text v-if="titleShow" :style="'color:' + titleColor">{{title}}</text> <!-- text组件的text绑定了响应式变量title、v-if指令绑定了titleShow、style绑定了titleColor-->
+	</view>
+	<image src="http://www.noexit.jpg" @error="imgerror"/>
+	<scroll-view >
+		<button type="primary" @click="buttonClick_changeText">修改文字内容</button>
+		<button @click="buttonClick_showHide">点击让文字组件显示或消失</button>
+		<button @click="buttonClick_changeColor">修改文字颜色</button>
+	</scroll-view>
+</template>
+<script setup>
+  let title = ref("Hello world") //定义一个响应式变量title，默认赋值为hello world
+	const buttonClick_changeText = () => {
+		title.value = "新文字内容" //对响应式变量title的.value属性赋值，界面上文字会自动同步修改
+	}
+	
+	let titleShow = ref(true) //决定标题文字是否显示
+	const buttonClick_showHide = () => {
+		titleShow.value = !titleShow.value //对响应式变量的.value属性赋值，界面上文字组件的v-if指令绑定了titleShow，所以会动态显示消失
+	}
+	
+	let titleColor = ref("black") //定义一个响应式变量titleColor，默认为黑色
+	const buttonClick_changeColor = () => {
+		titleColor.value = "red" //对响应式变量的.value属性赋值，界面上文字组件的style属性绑定了titleColor，所以会变为红色
+	}
+	
+	const imgerror = (event : ImageErrorEvent) => { // image组件加载失败时触发
+		console.log(event.type, event.detail); //错误的详情
+	}
+</script>
+```
+
+所有组件，都写在template标签下面。
 
-每个组件，包括如下几个部分：以组件名称为标记的开始标签和结束标签、组件内容、组件属性、组件属性值。
+- 组件的名称和开始/结束标签
+每个组件，都有开始和结束标签。\
+标签由尖括号包裹，它有开始标签和结束标签。结束标签的`<`后面用`/`来表示结束。结束标签也称为闭合标签。
+比如上面例子中template节点下第一个子节点 <view></view> ，view 表示这个组件的名称，<view>为开始标签，</view>为闭合标签。这是一个空的view视图组件。
 
-- 组件名称由尖括号包裹，称为标签，它有开始标签和结束标签。结束标签的`<`后面用`/`来表示结束。结束标签也称为闭合标签。如下面示例的`<component-name>`是开始标签，`</component-name>`是结束标签。
-- 在开始标签和结束标签之间，称为组件内容。如下面示例的`content`
-- 开始标签上可以写属性，属性可以有多个，多个属性之间用空格分割
-- 每个属性通过`=`赋值
+如果标签没有text内容或子组件，可以写成 自闭合标签，即只写 开始标签，并且 开始标签 以 `/>` 结尾。\
+比如上面例子中的 `<image src="http://www.noexit.jpg" @error="imgerror"/>`
 
-## 组件种类
+- 组件内容text
+指组件的内容区，即组件的开始标签和闭合标签之间的文字内容。\
+比如上面例子中button组件中的“修改文字内容”。\
+uni-app x中只有button、text组件等少数组件支持内容区，具体需查阅每个组件文档。
 
-uvue页面中，支持3种组件：
-1. 内置组件，即文档左侧的组件清单
-2. 自定义uvue组件，即开发者自己按照vue组件规范编写的uvue文件。这种组件一般由前端工程师编写。如果按照指定目录规范放置，在使用组件时无需import和注册，即[easycom组件规范](../vue/component.md#easycom)
-3. uts原生组件。由Android或iOS的原生开发者，按照uts插件的组件规范编写，它在编写时贴近但不完全是vue组件开发规范。不过对于组件的使用者来讲，用法就是标准的uvue组件了。[详见](../plugin/uts-component.md)
+- 子组件
+组件的内容区可以不是文字，而是下级组件。\
+比如上面例子中view组件的子组件是text组件，而scroll-view组件下面有3个button子组件。\
+并非所有组件都支持子组件，一般视图组件肯定是支持子组件的，其他组件需要查阅组件的文档说明。
 
-## 组件监听页面生命周期
+- 组件属性
+组件开始标签的组件名称后面，以空格分割的、以等号赋值的，不以v-或@开头的普通属性。\
+比如上面例子中button组件的[type属性](../component/button.md)，它定义了组件的一些控制参数，这是由组件作者给使用者提供的自定义参数。\
 
-`4.0` 起可通过组合式 API 实现组件中监听页面生命周期，[示例代码](../vue/component.md#component-lifecycle)。
+- 组件属性值
+在属性名后面用=号赋值的内容。\
+比如上面例子中button组件的type属性，其属性值为primary，`type="primary"`，即表示一个主按钮。\
 
+- 事件
+组件在发生某些事件后触发的函数。\
+比如上面例子中button组件的click事件。`@click="buttonClick_changeText"`。\
+buttonClick_changeText 是script里定义的一个函数。\
+事件区别于普通属性名的特征是以@开头，事件值指向一个函数（选项式指向一个method）。\
+很多事件还有event参数。\
+比如上面例子中image组件的error事件，绑定到imgerror函数，它有一个参数event对象，类型是ImageErrorEvent。接下来的代码打印了event对象的2个属性。
+
+- vue指令
+vue提供的一批特殊写法的属性，它们以v-开头，比如上面例子中text组件的v-if指令，绑定了一个titleShow的响应式变量，根据变量的true或false可以决定text组件是否显示。详见[vue指令](./built-in.md)\
+有一种特殊指令`v-bind`，一种把属性值变成script以便绑定响应式变量的写法，它的完整写法是 v-bind:普通属性名 = "属性值"，
+但它更常见的写法是简写为在普通属性前面加个冒号，比如上面例子中text组件的:style，`:style="'color:' + titleColor"`。\
+这个写法的意思是，text组件的style样式中，color属性的值绑定到了script定义的响应式变量titleColor上，修改这个响应式变量的值，text组件的文字颜色就会跟着变化。\
+绑定后属性值的内容变成了script，而不再是普通字符串。所以在属性值里写字符串需要再加单引号。
+
+
+组件们，有公共的属性和事件，[详见](../component/common.md)，也有组件特有的属性和事件，详见每个组件的文档。
+
+每个组件可以有多个属性、指令、事件，用空格分割。它们赋值的=号，前后可以允许0个或1个空格。
+
+所有组件与属性名都是**小写**，单词之间以连字符`-`连接。
+
+## 组件的分类
+
+uni-app x文档规范中有一批标准组件，同时也支持扩展自定义组件。
+
+### 1. 标准组件
+- 1.1 内置组件
+内置在uni-app x引擎中，开发者无需在代码中引用和注册的，可以直接使用。比如view、text、button...
+- 1.2 ext组件
+在app平台，对于不太常用、体积又大的官方基础组件，虽然其文档在uni-app x的官方文档中，但并没有内置到uni-app x引擎中。需要开发者下载ext组件到项目下才能使用。\
+出现这种情况一般是由于小程序规范里内置了该组件，而App端又不常用。（为了多端兼容，uni的组件规范是参考小程序组件规范制定的）\
+比如[animation-view组件](./animation-view.md)。\
+除了ext组件，还有ext api，它们情况类似，详细介绍：[ext插件](https://uniapp.dcloud.net.cn/api/extapi.html)
+
+### 2. 自定义组件
+
+标准组件只是一些基础组件。开发者还可以自行扩展组件，封装UI和逻辑，称为自定义组件。
+
+这类组件需要手动下载到项目中，或者自行在项目下编写。
+
+自定义组件，按开发方式分类，又有2种：前端uvue组件 和 原生uts组件
+
+- 2.1 前端uvue组件
+即开发者自己按照vue组件规范编写的uvue文件。这种组件一般由前端工程师编写。详见[uvue组件模型介绍](../vue/component.md)
+- 2.2 原生uts组件
+这是一种App平台专用的扩展机制。
+由Android或iOS的原生开发者，按照uts插件的组件规范编写，把原生的view嵌入到uvue页面上，它在编写时贴近但不完全是vue组件开发规范。\
+不过对于组件的使用者来讲，用法就是标准的uvue组件了。详见[uts组件开发指南](../plugin/uts-component.md)\
+uts原生组件，下载组件到项目后（或自己按规范编写），在页面template里直接引用即可。无需导入注册组件。
+
+对于前端uvue组件，又有2种引用方式。
+1. 传统vue组件：
+需要先import、注册，然后再在页面template中使用。[详见](../vue/component.md#manual-import-component)
+2. easycom组件
+easycom组件是uni-app提供的一种易用方式，它通过一个路径规范让编译器知道组件的位置，实现自动的import和注册。详见[easycom组件规范](../vue/component.md#easycom)
+
+在uni插件市场（[https://ext.dcloud.net.cn/](https://ext.dcloud.net.cn/)），下载的组件基本都是easycom组件规范或uts原生组件规范，都是在页面里可以直接引用的。
+
+插件市场的功能较多，可以看介绍了解：[详见](https://uniapp.dcloud.net.cn/plugin/plugin-ext-introduction.html)
+
+## 其他组件概念
+- datacom
+`datacom`是一种数据驱动的组件，只需要给出符合格式的数据就可以使用。它是uvue组件的子类，尤其适合云端一体组件。详见：[datacom介绍](https://uniapp.dcloud.net.cn/component/datacom.html)
+
+- uni_modules
+`uni_modules`是uni-app生态的包管理方案。非内置组件，可以放在项目下任意位置，也可以封装在`uni_modules`下。一般对外提供的成熟组件都应该封装在`uni_modules`下。\
+如果还不了解`uni_modules`，那务必需要阅读：[uni_modules介绍](https://uniapp.dcloud.net.cn/plugin/uni_modules.html)
+
+
+## 组件的编写
+- 前端uvue组件的开发指南：[详见](../vue/component.md)
+- uts原生组件的开发指南：[详见](../plugin/uts-component.md)
+
+组件开发完毕后可发布到插件市场，插件作者指南：[详见](https://uniapp.dcloud.net.cn/plugin/publish.html)
+
+<!-- TODO下面这段应该挪走 -->
 ## 调用组件方法@methods
 
 需要把组件分为 内置组件、easycom组件、非easycom组件，这3种组件有不同的方法调用方式。[详情](../vue/component.md#page-call-component-method)
@@ -76,7 +213,7 @@ easycom组件，用法和内置组件一样。也是使用 `this.$refs` 获取
 
 ### vue 与 uvue 不同文件后缀的优先级 @priority
 
-新建组件时，默认组件的后缀名为.uvue，但也支持.vue。
+新建组件时(注意不是新建页面)，默认组件的后缀名为.uvue，但也支持.vue。
 
 .vue里面写uvue的语法，可以正常被.uvue页面引用和编译。
 

docs/vue/README.md

@@ -39,46 +39,48 @@ HBuilderX/uni-app x，会跟踪vue版本的升级，版本映射表如下
 
 注意html中，根节点是`<html>`，`<script>`和`<style>`是子节点。但在uvue中，这3个节点都是一级节点。
 
-一个简单的选项式页面示例：
+vue的script分组合式和选项式，下面先提供1个基于组合式的数据绑定和修改的示例，点击按钮，修改按钮的文字。
+
 ```vue
 <template>
 	<view class="content">
+		<!-- button的文字绑定了响应式变量title，点击事件绑定了buttonClick方法-->
 		<button @click="buttonClick">{{title}}</button>
 	</view>
 </template>
 
-<script>
-	export default {
-		data() {
-			return {
-				title: "Hello world", // 定义绑定在页面上的data数据
-			}
-		},
-		onLoad() {
-			// 页面启动的生命周期，这里编写页面加载时的逻辑
-		},
-		methods: {
-			buttonClick: function () {
-				console.log("按钮被点了")
-			},
+<script setup>
+  let title = ref("Hello world") //定义一个响应式变量title，默认赋值为Hello world
+	const buttonClick = () => {
+		title.value = "按钮被点了" //对响应式变量title的.value属性赋值，界面上button的文字会自动同步修改
 	}
+	/*
+		function buttonClick() { // 简单的function方式也可以用，但在不同平台的作用域有细微差异。所以一般推荐上方箭头函数的写法。
+		title.value = "按钮被点了"
 	}
+	*/
+	onLoad(() => {
+		// 页面启动的生命周期，这里编写页面加载时的逻辑
+	})
 </script>
 
 <style>
 	.content {
 		width: 750rpx;
-		background-color: white;
 	}
 </style>
 ```
 
+可以看出整体和html还是很接近的。但响应式变量和绑定机制，可以免去写大量的dom操作代码，让开发更高效轻松。
+
+基于选项式的示例，下面章节会提供。
+
 ## template
 
 template中文名为`模板`，它类似html的标签。但有2个区别：
 
 1. html中 `script` 和 `style` 是 html 的二级节点。但在 uvue 文件中，`template`、`script`、`style` 这3个是平级关系。
-2. html 中写的是 web 标签，但 vue 的 `template` 中写的全都是 vue 组件（包括[内置基础组件](../component/README.md)、自定义uvue组件、[uts原生插件组件](../plugin/uts-component.md)），每个组件支持属性、事件、vue 指令，还可以绑定 vue 的 data 数据。
+2. html 中写的是 web 标签，但 vue 的 `template` 中写的全都是 vue 组件（包括[内置基础组件](../component/README.md)、自定义前端uvue组件、[uts原生插件组件](../plugin/uts-component.md)），每个组件支持属性、事件、vue 指令，还可以绑定 vue 的 data 数据。
 
 组件，即component，是vue中非常重要的概念，或者说现代开发框架都离不开组件概念。
 
@@ -86,19 +88,39 @@ template中文名为`模板`，它类似html的标签。但有2个区别：
 
 在 uni-app x 中， `<view>`是最基本的视图容器组件，`<text>`则是文字组件，`<button>`是按钮组件。这些都是[内置组件](../component/README.md)
 
-一个页面或组件只能有一个template标签，template下面可以有多个二级节点，如下：
+一个页面或组件只能有一个template标签，template下面可以有多个二级节点，即多个根组件。如下：
 
 ```vue
 <template>
 	<view>
-		<text>标题</text>
+		<text v-if="titleShow" :style="'color:' + titleColor">{{title}}</text> <!-- text组件的text绑定了响应式变量title、v-if指令绑定了titleShow、style绑定了titleColor-->
 	</view>
-	<scroll-view>
-
+	<scroll-view >
+		<button @click="buttonClick_changeText" type="primary">修改文字内容</button>
+		<button @click="buttonClick_showHide">点击让文字组件显示或消失</button>
+		<button @click="buttonClick_changeColor">修改文字颜色</button>
 	</scroll-view>
 </template>
+<script setup>
+  let title = ref("Hello world") //定义一个响应式变量title，默认赋值为hello world
+	const buttonClick_changeText = () => {
+		title.value = "新文字内容" //对响应式变量title的.value属性赋值，界面上文字会自动同步修改
+	}
+	
+	let titleShow = ref(true) //决定标题文字是否显示
+	const buttonClick_showHide = () => {
+		titleShow.value = !titleShow.value //对响应式变量的.value属性赋值，界面上文字组件的v-if指令绑定了titleShow，所以会动态显示消失
+	}
+	
+	let titleColor = ref("black") 
+	const buttonClick_changeColor = () => {
+		titleColor.value = "red" //对响应式变量的.value属性赋值，界面上文字组件的style属性绑定了titleColor，所以会变色
+	}
+</script>
 ```
 
+组件有很多概念，属性、事件、指令。如果还不了解相关概念，请参阅 [组件介绍](../compiler/README.md)
+
 ## script
 
 script中编写逻辑代码。
@@ -107,10 +129,36 @@ uvue中只能有一个script标签。
 
 script标签的属性如下：
 - lang
-lang 仅支持uts，不管script的lang属性写成什么，都按uts编译。
+lang 仅支持uts，不管script的lang属性写成什么，都按uts编译。注意在iOS的js引擎驱动的uvue页面里，uts会被编译为js。
 - setup
 setup属性声明代表script里的代码为组合式写法，如果没有setup属性则为选项式写法。
 
+### 组合式和选项式的区别
+
+vue最初只有选项式API，从vue3起，新增了组合式API。
+
+所谓选项式，就是把script的内容在export default {} 中约定不同的对象，在其中通过多个选项的对象来定义data、method和生命周期。
+
+框定好这些后，开发者就在这个框框里分别写自己的业务逻辑。
+
+这种方式易用但不够灵活。所以在vue3以前，部分开发者会认为react更难学、更灵活，所以更高级。
+
+vue3新增的组合式API，是纯编程的，解决了选项式不够灵活的问题。同时维持了易学的特点。让vue变的即容易、又灵活。
+
+uni-app x不再支持vue2。在vue3中，组合式和选项式是可以混合使用的。
+1. 可以A页面使用组合式，B页面使用选项式，互相跳转。
+2. 可以页面使用组合式，其中的某些组件使用选项式。反之亦然。
+3. 一个页面或组件内，可以混合使用组合式和选项式
+- 在选项式的script里，可通过setup选项，在其中编写组合式代码
+- 在组合式script里（即script有setup属性），也可以通过defineOptions来定义选项式写法
+
+但注意不支持一个页面/组件有2个script，分别写选项式和组合式。
+
+开发者可以根据自己的喜好选择2种写法，但还有几个差别需要注意：
+1. 组合式API的组件，可以监听引用其页面的页面级生命周期。而选项式是不能的。有相关需求的组件，需使用组合式API，或在选项式中使用setup函数。[详见](./component.md#component-page-lifecycle)
+2. 选项式的type类型定义在`export default {}`外，这些都是应用级全局的，略微影响性能。[见下](#export-default-out)
+3. app.uvue和uts组件插件的index.vue，目前只支持选项式。
+
 ### 组合式API
 组合式 API，也称 Composition API，或 setup函数。
 
@@ -126,17 +174,23 @@ setup属性声明代表script里的代码为组合式写法，如果没有setup
 ```vue
 <template>
 	<view>
+		<!-- button的文字绑定了响应式变量title，点击事件绑定了buttonClick方法-->
 		<button @click="buttonClick">{{title}}</button>
 	</view>
 </template>
 
 <script setup>
-  let title = ref("Hello world") //定义一个响应式变量。类似于选项式的定义data
-	function buttonClick() { //方法不再需要写在method下面。这里从简使用了function，实际业务中推荐使用箭头函数，有更好的平台一致性
-	  console.log("按钮被点了")
+  let title = ref("Hello world") //定义一个响应式变量title，默认赋值为Hello world
+	const buttonClick = () => {
+		title.value = "按钮被点了" //对响应式变量title的.value属性赋值，界面上button的文字会自动同步修改
+	}
+	/*
+		function buttonClick() { // 简单的function方式也可以用，但在不同平台的作用域有细微差异。所以一般推荐上方箭头函数的写法。
+		title.value = "按钮被点了"
 	}
-	onReady(() => {
-		console.log("页面onReady触发") // 页面生命周期，编写页面加载后的逻辑
+	*/
+	onLoad(() => {
+		// 页面启动的生命周期，这里编写页面加载时的逻辑
 	})
 </script>
 
@@ -161,21 +215,27 @@ setup属性声明代表script里的代码为组合式写法，如果没有setup
 				title: "Hello world", // 定义绑定在页面上的data数据
 			}
 		},
-		onReady() {
-			console.log("页面onReady触发") // 页面生命周期，编写页面加载后的逻辑
+		onLoad() {
+			// 页面启动的生命周期，这里编写页面加载时的逻辑
 		},
 		methods: {
 			buttonClick: function () {
-				console.log("按钮被点了")
+				this.title= "按钮被点了" //对响应式变量title赋值，界面上button的文字会自动同步修改
 			},
 		}
 	}
 </script>
 ```
 
-#### `export default` 外的代码
+对比之前组合式的、相同业务逻辑的代码，可以看到两种方式的差异：
+1. 选项式由于有框框的存在，看起来结构清晰些，但代码行数也更长
+2. 组合式更灵活，代码更短。高级开发者也可以自己保证代码结构的清晰整洁。但初学者如果代码写的很长，容易乱糟糟
+
+上述代码比较简单，如果涉及到响应式变量的类型定义，那么会更明显的感受到组合式的灵活和简洁。
+
+#### `export default` 外的代码@export-default-out
 
-既然有写在写`export default {}`里的代码，那么就有 `export default {}` 外面的代码。
+选项式主代码在`export default {}`里。但既然有`export default {}`里的代码，那么就有 `export default {}` 外面的代码。
 
 写在外面一般有几种情况：
 

docs/vue/component.md

@@ -6,15 +6,12 @@
 
 这就是vue的组件机制，把视图template、script、style都封装到独立的uvue组件文件中，在其他需要的地方使用组件的名称进行引用。
 
-每个组件，包括如下几个部分：以组件名称为标记的开始标签和结束标签、组件内容、组件属性、组件属性值。
-
-- 组件名称由尖括号包裹，称为标签，它有开始标签和结束标签。结束标签的`<`后面用`/`来表示结束。结束标签也称为闭合标签。如`<component-name>`是开始标签，`</component-name>`是结束标签
-- 在开始标签和结束标签之间，称为组件内容
-- 开始标签上可以写属性，属性可以有多个，多个属性之间用空格分割
-- 每个属性通过`=`赋值
+每个组件，包括如下几个部分：以组件名称为标记的开始标签和结束标签、组件text内容、组件属性、组件属性值。
 
 组件还可以封装方法、事件、插槽，提供了[组件的生命周期](#component-lifecycle)，提供了组件和页面的[互通信机制](#use-and-communication)，满足了各种高级需求。
 
+如果您还不了解这些概念，请务必先阅读 [组件概述文档](../compiler/README.md)
+
 ## 组件内容构成 @component-structure
 
 uni-app x 组件基于 vue 单文件组件规范，一个组件内，有 3 个根节点标签：
@@ -366,7 +363,7 @@ Uni`组件名(驼峰)`Element
 
 ::: warning 注意
 1. onAppHide、onAppShow 目前只有 Android 支持
-2. onPageHide、onPageShow 需要写在 setup 函数或者 `<script setup>` 中才能生效
+2. onPageHide、onPageShow 需要写在选项式的 setup 函数 或者 组合式 `<script setup>` 中才能生效
 :::
 
 示例 [详情](<!-- VUEJSON.E_lifecycle.page_monitor-page-lifecycle-composition.gitUrl -->)
@@ -385,7 +382,7 @@ Uni`组件名(驼峰)`Element
 
 ## 组件的生命周期 @component-lifecycle
 
-#### 组件生命周期（选项式 API）兼容性 @component-lifecycle-options-compatibility
+### 组件生命周期（选项式 API）兼容性 @component-lifecycle-options-compatibility
 
 <!-- VUEJSON.options_lifecycle.compatibility -->
 

docs/vue/data-bind.md

@@ -71,7 +71,7 @@ const counter = ref({ count: 0 } as Counter) // 而不是 ref<Counter>({count: 0
 - 通过ref定义了3个响应式变量：count1、count2、counter（注意是小写），并赋值了初始值。
 - 在模板template中通过`{{}}`的方式绑定和显示在text组件的内容区中。即右边预览区显示的3行内容，显示了3个响应式变量的初始值。
 - 点击按钮“increment”，触发`increment()`，在这个方法里通过`.value`属性给响应式变量自增。然后界面上3行内容会被自动更新为新值。
-
+<!-- TODO 为什么加2 -->
 示例 [详情](<!-- VUEJSON.E_reactivity.core_ref_ref.gitUrl -->)
 
 ::: preview <!-- VUEJSON.E_reactivity.core_ref_ref.webUrl -->