组件使用的入门教程

• 组件是视图层的基本组成单元。
• 组件是一个单独且可复用的功能模块的封装。

每个组件，包括如下几个部分：以组件名称为标记的开始标签和结束标签、组件内容、组件属性、组件属性值。

• 组件名称由尖括号包裹，称为标签，它有开始标签和结束标签。结束标签的 < 后面用 / 来表示结束。结束标签也称为闭合标签。如下面示例的 <component-name> 是开始标签， </component-name> 是结束标签。
• 在开始标签和结束标签之间，称为组件内容。如下面示例的 content
• 开始标签上可以写属性，属性可以有多个，多个属性之间用空格分割。如下面示例的 property1 和 property2 。注意闭合标签上不能写属性。
• 每个属性通过 = 赋值。如下面的示例中，属性 property1 的值被设为字符串 value 。

注意：所有组件与属性名都是小写，单词之间以连字符-连接。

Vue

<component-name property1="value" property2="value">
  content
</component-name>

<component-name property1="value" property2="value">
  content
</component-name>

下面是一个基本组件的实例，在一个 vue 页面的根 <view> 组件下插入一个 <button> 组件。给这个组件的内容区写上文字“按钮”，同时给这个组件设置了一个属性 “size” ，并且 “size” 属性的值设为了 “mini” 。

注：按照 vue 单文件组件规范，每个vue文件的根节点必须为 <template> 。

Vue

<template>
  <view>
    <button size="mini">按钮</button>
  </view>
</template>

<template>
  <view>
    <button size="mini">按钮</button>
  </view>
</template>

通过了解 button 组件的文档，我们知道上述代码将在页面中绘制一个按钮，按钮显示的文字是“按钮”，按钮的大小是小尺寸的。

组件的属性类型

组件的属性，有多种类型：

类型	描述	注解
Boolean	布尔值	组件写上该属性，不管该属性等于什么，其值都为 true，只有组件上没有写该属性时，属性值才为 false。如果属性值为变量，变量的值会被转换为 Boolean 类型。
Number	数字	1, 2.5
String	字符串	"string"
Array	数组	[ 1, "string" ]
Object	对象	{ key: value }
EventHandler	事件处理函数名	handlerName 是 methods 中定义的事件处理函数名
Any	任意属性

下面的例子演示了组件的属性设置boolean值和数字的例子。注意false作为一个js变量，在组件的属性中使用时，属性前面需增加 : 冒号前缀，属性值仍使用引号包裹，但引号里不是字符串，而是 js 。

Vue

<template>
  <view>
    <button
      size="mini"
      :disabled="false"
      hover-start-time="20"
    >按钮</button>
  </view>
</template>

<template>
  <view>
    <button
      size="mini"
      :disabled="false"
      hover-start-time="20"
    >按钮</button>
  </view>
</template>

公共属性列表

每个组件都有各自定义的属性，但所有uni-app的组件，都有如下属性：

属性名	类型	描述	注解
id	String	组件的唯一标示	一般用于获取组件上下文对象（如： VideoContext ），需要保持整个页面唯一
ref	String	vue 中组件的唯一标示	用来给子组件注册引用信息，详见 Vue 文档
class	String	组件的样式类	在对应的 css 中定义的样式类
style	String	组件的内联样式	可以动态设置的内联样式
hidden	Boolean	组件是否隐藏	所有组件默认是显示的
data-*	Any	自定义属性	组件上触发的事件时，会发送给事件处理函数
@*	EventHandler	组件的事件	详见各组件详细文档，事件绑定参考 事件处理器

除了上述公共属性，还有一类特殊属性以 v- 开头，称之为vue指令，如 v-if 、 v-else 、 v-for 、 v-model 。详见 vue 指令

在组件中使用 script 的 data 变量

组件中可以使用 script 的 data 中定义的变量，但组件的属性中使用和内容区使用的用法不一样。

• 在 text 内容区使用时，使用两个花括号来包裹，如下面的 buttonText
• 在属性值中使用时，属性名的前面要加冒号前缀

下面的 button 组件示例，等价于上一个的示例。只不过静态内容改成动态 js 。

Vue

<template>
  <view>
    <button
      size="mini"
      :disabled="buttondisble"
      hover-start-time="20"
    >{{buttonText}}</button>
  </view>
</template>

<template>
  <view>
    <button
      size="mini"
      :disabled="buttondisble"
      hover-start-time="20"
    >{{buttonText}}</button>
  </view>
</template>

Script

<script>
  export default {
    data() {
      return {
        buttonText: '按钮',
        buttondisble: false,
      },
    },
  };
</script>

<script>
  export default {
    data() {
      return {
        buttonText: '按钮',
        buttondisble: false,
      },
    },
  };
</script>

组件的事件

每个组件都有“事件”。事件就是在指定的条件下触发某个 js 方法。

比如 button 组件，有点击事件，也就是当手机用户点击这个 button 组件时，会触发这个事件。

事件也是组件的属性，只不过这类属性以 @ 为前缀。

事件的属性值，指向一个在 script 的 methods 里定义过的 js方法，还可以给方法传参数。

下面是组件事件的示例：

• click 是 button 组件的点击事件，在用户点击这个 button 时触发
• click 指向了 methods 中定义的 goto 方法，并且传递了一个参数 /pages/about/about

Vue

<template>
  <view>
    <button
      size="mini"
      @click="() => goto('/pages/about/about')"
    >按钮</button>
  </view>
</template>

<template>
  <view>
    <button
      size="mini"
      @click="() => goto('/pages/about/about')"
    >按钮</button>
  </view>
</template>

Script

<script>
  export default {
    methods: {
      goto(theUrl) {
        console.log("按钮被点击了，且传入的参数是：" + theUrl);
      },
    },
  };
</script>

<script>
  export default {
    methods: {
      goto(theUrl) {
        console.log("按钮被点击了，且传入的参数是：" + theUrl);
      },
    },
  };
</script>

基础组件

qinjs 的组件，分为基础组件和扩展组件。

基础组件在 qinjs 框架中已经内置，无需将内置组件的文件导入项目，也无需注册内置组件，随时可以直接使用，比如 <view> 组件。

除了基础组件，都称为扩展组件。扩展组件需要将组件导入项目中才可以使用。

qinjs 为开发者提供了一系列基础组件，类似 HTML 里的基础标签元素。

但 qinjs 的组件与 HTML 不同，而是与小程序相同，可更好的满足手机端的使用习惯。

虽然不推荐使用HTML标签，但实际上如果开发者写了 div 等标签，在编译到非H5平台时也会被编译器转换为 view 标签，类似的还有 span 转 text 、 a 转 navigator 等，包括 css 里的元素选择器也会转。但为了管理方便、策略统一，新写代码时仍然建议使用 view 等组件。

开发者可以通过组合这些基础组件进行快速开发。在需要复用的情况下可封装成扩展组件。

qinjs 基础组件规范，与小程序规范相近。如果了解小程序开发的话，qinjs 的基础组件会感觉很熟悉。但需要注意组件上的事件绑定，需要以 vue 的事件绑定语法来绑定，如 bindchange="eventName" 事件，需要写成 @change="eventName"

Vue

<picker
  mode="date"
  :value="date"
  start="2015-09-01"
  end="2020-09-01"
  @change="bindDateChange"
>
  <view class="picker">
    当前选择: {{date}}
  </view>
</picker>

<picker
  mode="date"
  :value="date"
  start="2015-09-01"
  end="2020-09-01"
  @change="bindDateChange"
>
  <view class="picker">
    当前选择: {{date}}
  </view>
</picker>

基础组件列表

基础组件分为以下十几大类：

视图容器（View Container）：

组件名	说明
view	视图容器，类似于 HTML 中的 div
scroll-view	可滚动视图容器
swiper	滑块视图容器，比如用于轮播 banner

基础内容（Basic Content）：

组件名	说明
text	文字
rich-text	富文本显示组件
progress	进度条

表单组件（Form）：

标签名	说明
button	按钮
checkbox	多项选择器
form	表单
input	输入框
label	标签
picker	弹出式列表选择器
picker-view	窗体内嵌式列表选择器
radio	单项选择器
slider	滑动选择器
switch	开关选择器
textarea	多行文本输入框

媒体组件（Media）：

组件名	说明
camera	相机
image	图片
video	视频

地图（Map）：

组件名	说明
map	地图

webview（Web-view）：

组件名	说明
web-view	web浏览器组件

页面属性配置

组件名	说明
page-meta	页面属性配置节点

各平台专有组件

在小程序平台平台，还有一些专有组件，比如 open-data 。

扩展组件的意义

虽然所有的业务需求都可以通过基础组件满足，但仅有基础组件是低效的，实际开发中会有很多封装的组件。

比如我们需要一个五角星点击评分的组件，在插件市场里可以获取到。

把这个uni-rate组件导入到你的 qinjs 项目下，在需要的 vue 页面里引用它，就可以在指定的地方显示出这个五角星组件。

Vue

<!-- 在index.vue页面引用 uni-rate 组件-->
<template>
  <view>
    <uni-rate /><!-- 这里会显示一个五角星，并且点击后会自动亮星 -->
  </view>
</template>

<!-- 在index.vue页面引用 uni-rate 组件-->
<template>
  <view>
    <uni-rate /><!-- 这里会显示一个五角星，并且点击后会自动亮星 -->
  </view>
</template>

封装扩展组件的优势：

• 可以将组件进行任意次数的复用。
• 合理的划分组件，有助于提高应用性能。
• 代码更加方便组织和管理，并且扩展性也更强，便于多人协同开发。
• 组件化开发能大幅度提高应用开发效率、测试性、复用性等。

组件的类别

qinjs 支持的组件分为 vue 组件和小程序自定义组件。

如果你还不了解这两种组件，可以参阅各自的文档

• vue 组件：文档
• 小程序自定义组件：其规范不是 vue 规范，而是小程序规范，文档

日常开发来讲，推荐使用 vue 组件。 qinjs 支持小程序组件主要是为了兼容更多生态资源。

如果扩展组件符合 qinjs 的 easycom 组件规范，则可以免注册，直接使用。比如 qin-ui 扩展组件就符合 easycom 组件规范。

如果组件不符合 easycom 规范，则需要在代码里手动 import 和注册组件，然后才能使用。

除了 easycom 规范外，扩展组件还有很多概念，比如 qin_module 、 datacom 、原生组件。

接下来一一讲解。

easycom 组件规范

传统 vue 组件，需要安装、引用、注册，三个步骤后才能使用组件。easycom将其精简为一步。

只要组件安装在项目的components目录下、qin_modules 或qin_modules目录下，并符合components/组件名称/组件名称.vue目录结构（注意：当同时存在vue时， qinjs 项目优先使用 vue 文件。就可以不用引用、注册，直接在页面中使用。

比如前述举例的uni-rate组件，它导入到 qinjs 项目后，存放在了目录/components/uni-rate/uni-rate.vue

同时它的组件名称也叫 uni-rate ，所以这样的组件，不用在 script 里注册和引用。 如下：

Vue

<template>
  <view>
    <uni-rate /><!-- 这里会显示一个五角星，并且点击后会自动亮星 -->
  </view>
</template>

<template>
  <view>
    <uni-rate /><!-- 这里会显示一个五角星，并且点击后会自动亮星 -->
  </view>
</template>

Script

<script>
  // 这里不用import引入，也不需要在components内注册uni-list组件。template里就可以直接用
  export default {
  };
</script>

<script>
  // 这里不用import引入，也不需要在components内注册uni-list组件。template里就可以直接用
  export default {
  };
</script>

不管 components 目录下安装了多少组件， easycom 打包后会自动剔除没有使用的组件，对组件库的使用尤为友好。

组件库批量安装，随意使用，自动按需打包。以官方的 qin-ui 为例，在HBuilderX新建项目界面选择 qin-ui 项目模板，只需在页面中敲u，拉出大量组件代码块，直接选择，即可使用。大幅提升开发效率，降低使用门槛。

在插件市场下载符合 components/组件名称/组件名称.vue 目录结构的组件，均可直接使用。

easycom 是自动开启的，不需要手动开启。

如果你的组件名称或路径不符合 easycom 的默认规范，可以在 pages.json 的 easycom 节点进行个性化设置，自定义匹配组件的策略。另见

如果不使用 easycom ，手动引用和注册 vue 组件，则需要分3步写如下代码：

1. import 导入组件
2. components 里注册组件
3. template 中使用组件

Vue

<template>
  <view>
    <uni-rate text="1"></uni-rate>
  </view>
</template>

<template>
  <view>
    <uni-rate text="1"></uni-rate>
  </view>
</template>

Script

<script>
  import uniRate from '@/components/uni-rate/uni-rate.vue';
  export default {
    components:{ uniRate }
  }
</script>

<script>
  import uniRate from '@/components/uni-rate/uni-rate.vue';
  export default {
    components:{ uniRate }
  }
</script>

qin_module规范

qin_module 其实不止服务于组件，它可以服务于组件、 js 库、页面、项目等所有插件市场所支持的种类。

符合 qin_module 规范的组件都在项目的 qin_modules 目录下，以插件 id 为目录存放。（项目模板不放在 qin_modules 目录下）

qin_module 还支持云端一体的插件。

qin_module 有详细的专项文档，请另行查阅 qin_module 规范。

原生组件和原生插件

基础组件里的原生组件

qinjs 的基础组件里，有一批原生组件，如 video 、 map ...

这些组件如果用于 vue 页面，也就是 webview 渲染时，会造成层级高于普通前端组件的情况。

它们的层级需要使用 cover-view 等特殊组件才能覆盖，同时在使用中有些需要注意的事情。

如何封装组件

封装组件涉及的知识点较多，相关文档详见： vue 组件详解