diff --git a/docs/component/README.md b/docs/component/README.md index 0d33f1c32824c3397888212f40392bd5d5216c4b..3964aa413b36ac45e3c85b32a1afada1de225a13 100644 --- a/docs/component/README.md +++ b/docs/component/README.md @@ -1,28 +1,165 @@ -# uvue组件概述 +# 组件概述 -## 定义 +## 组件定义 - 组件是视图层的基本组成单元。 -- 组件是一个单独且可复用的功能模块的封装。 +- 组件是一个单独且可复用的UI及配套功能模块的封装。 + +我们知道js逻辑可以封装为函数或类库。而对于页面上可视的元素,则可以将ui、样式、逻辑一起封装为组件。 + +组件涉及较多的概念,包括组件名称、开头和闭合标签、组件属性、组件属性值、组件事件、组件vue指令、组件text内容、子组件。 + +我们先看一个简单的例子: +```vue + + content + +``` + +上面的代码,是一个组件,组件名为component-name,这个组件有2个属性,property1和property2,这2个属性的属性值都是"value",组件的text内容为"content" + +然后我们看一个全面但有些复杂的示例,这段示例融合了组件的各种概念: + +```vue + + +``` + +所有组件,都写在template标签下面。 + +- 组件的名称和开始/结束标签 +每个组件,都有开始和结束标签。\ +标签由尖括号包裹,它有开始标签和结束标签。结束标签的`<`后面用`/`来表示结束。结束标签也称为闭合标签。 +比如上面例子中template节点下第一个子节点 ,view 表示这个组件的名称,为开始标签,为闭合标签。这是一个空的view视图组件。 + +如果标签没有text内容或子组件,可以写成 自闭合标签,即只写 开始标签,并且 开始标签 以 `/>` 结尾。\ +比如上面例子中的 `` + +- 组件内容text +指组件的内容区,即组件的开始标签和闭合标签之间的文字内容。\ +比如上面例子中button组件中的“修改文字内容”。\ +uni-app x中只有button、text组件等少数组件支持内容区,具体需查阅每个组件文档。 + +- 子组件 +组件的内容区可以不是文字,而是下级组件。\ +比如上面例子中view组件的子组件是text组件,而scroll-view组件下面有3个button子组件。\ +并非所有组件都支持子组件,一般视图组件肯定是支持子组件的,其他组件需要查阅组件的文档说明。 + +- 组件属性 +组件开始标签的组件名称后面,以空格分割的、以等号赋值的,不以v-或@开头的普通属性。\ +比如上面例子中button组件的[type属性](../component/button.md),它定义了组件的一些控制参数,这是由组件作者给使用者提供的自定义参数。\ + +- 组件属性值 +在属性名后面用=号赋值的内容。\ +比如上面例子中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原生组件规范,都是在页面里可以直接引用的。 -- 组件名称由尖括号包裹,称为标签,它有开始标签和结束标签。结束标签的`<`后面用`/`来表示结束。结束标签也称为闭合标签。如下面示例的``是开始标签,``是结束标签。 -- 在开始标签和结束标签之间,称为组件内容。如下面示例的`content` -- 开始标签上可以写属性,属性可以有多个,多个属性之间用空格分割 -- 每个属性通过`=`赋值 +插件市场的功能较多,可以看介绍了解:[详见](https://uniapp.dcloud.net.cn/plugin/plugin-ext-introduction.html) -## 组件种类 +## 其他组件概念 +- datacom +`datacom`是一种数据驱动的组件,只需要给出符合格式的数据就可以使用。它是uvue组件的子类,尤其适合云端一体组件。详见:[datacom介绍](https://uniapp.dcloud.net.cn/component/datacom.html) -uvue页面中,支持3种组件: -1. 内置组件,即文档左侧的组件清单 -2. 自定义uvue组件,即开发者自己按照vue组件规范编写的uvue文件。这种组件一般由前端工程师编写。如果按照指定目录规范放置,在使用组件时无需import和注册,即[easycom组件规范](../vue/component.md#easycom) -3. uts原生组件。由Android或iOS的原生开发者,按照uts插件的组件规范编写,它在编写时贴近但不完全是vue组件开发规范。不过对于组件的使用者来讲,用法就是标准的uvue组件了。[详见](../plugin/uts-component.md) +- uni_modules +`uni_modules`是uni-app生态的包管理方案。非内置组件,可以放在项目下任意位置,也可以封装在`uni_modules`下。一般对外提供的成熟组件都应该封装在`uni_modules`下。\ +如果还不了解`uni_modules`,那务必需要阅读:[uni_modules介绍](https://uniapp.dcloud.net.cn/plugin/uni_modules.html) -## 组件监听页面生命周期 -`4.0` 起可通过组合式 API 实现组件中监听页面生命周期,[示例代码](../vue/component.md#component-lifecycle)。 +## 组件的编写 +- 前端uvue组件的开发指南:[详见](../vue/component.md) +- uts原生组件的开发指南:[详见](../plugin/uts-component.md) +组件开发完毕后可发布到插件市场,插件作者指南:[详见](https://uniapp.dcloud.net.cn/plugin/publish.html) + + ## 调用组件方法@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页面引用和编译。 diff --git a/docs/vue/README.md b/docs/vue/README.md index ffce57f4f73ab15eabbba493d73af4de933b7f8c..acf144a482a5ab064c2fe67c2b6acb38608c2a30 100644 --- a/docs/vue/README.md +++ b/docs/vue/README.md @@ -39,46 +39,48 @@ HBuilderX/uni-app x,会跟踪vue版本的升级,版本映射表如下 注意html中,根节点是``,` ``` +可以看出整体和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 中, ``是最基本的视图容器组件,``则是文字组件,`