mirror of https://github.com/layui/layui
docs: 重构 component 组件构建器文档
贤心
parent
3460ee2d6a
commit
6338c22ec1
|
|
@ -7,13 +7,13 @@ toc: true
|
|||
|
||||
> 组件构建器 `component` 是 2.10 版本新增的重要模块，旨在为 Layui 2 系列版本逐步构建统一 API 规范的组件。
|
||||
|
||||
<h2 id="api" lay-toc="{}">API</h2>
|
||||
<h2 id="api" lay-toc="{hot: true}">API</h2>
|
||||
|
||||
| API | 描述 |
|
||||
| --- | --- |
|
||||
| [layui.component(options)](#create) | 创建组件 |
|
||||
|
||||
<h3 id="create" lay-toc="{hot: true, level: 2}">创建组件</h3>
|
||||
<h3 id="create" lay-toc="{level: 2}">创建组件</h3>
|
||||
|
||||
`layui.component(options);`
|
||||
|
||||
|
|
@ -30,73 +30,168 @@ layui.define('component', function(exports) {
|
|||
// 创建组件
|
||||
var component = layui.component({
|
||||
name: 'tabs', // 组件名称
|
||||
config: {}, // 组件默认配置项
|
||||
render: function() {
|
||||
// 组件渲染逻辑
|
||||
config: { // 组件默认配置项
|
||||
// …
|
||||
},
|
||||
render: function() { // 组件渲染逻辑
|
||||
// …
|
||||
},
|
||||
// 其他选项
|
||||
});
|
||||
|
||||
// 将创建组件时返回的 `component` 对象作为组件的接口输出
|
||||
// 接口将继承基础成员，如 render, reload, set 等方法
|
||||
// 组件将继承通用的基础接口，如 render, reload, set 等方法
|
||||
exports(component.CONST.MOD_NAME, component);
|
||||
});
|
||||
```
|
||||
|
||||
<h3 id="options" lay-toc="{level: 2, hot: true}">属性配置</h3>
|
||||
<h3 id="options" lay-toc="{level: 2}">属性配置</h3>
|
||||
|
||||
<div>
|
||||
{{- d.include("/component/detail/options.md") }}
|
||||
</div>
|
||||
|
||||
<h2 id="prototype" lay-toc="{hot: true}">原型</h2>
|
||||
<h2 id="export" lay-toc="{}">基础接口 🔥</h2>
|
||||
|
||||
创建组件时的 `layui.component()` 方法返回的对象中包含 `Class` 构造函数，它通常用于扩展组件的原型，以灵活实现组件的个性化定制。但一般不推荐重写 `component.js` 原型中已经定义的基础方法，如：`init, reload, cache`。
|
||||
|
||||
```
|
||||
layui.define('component', function(exports) {
|
||||
// 创建组件
|
||||
var component = layui.component({
|
||||
// …
|
||||
});
|
||||
|
||||
// 获取构造器
|
||||
var Class = component.Class;
|
||||
|
||||
// 扩展原型
|
||||
Class.prototype.xxx = function() {
|
||||
// …
|
||||
};
|
||||
Class.prototype.aaa = function() {
|
||||
// …
|
||||
};
|
||||
|
||||
// 输出组件接口
|
||||
exports(component.CONST.MOD_NAME, component);
|
||||
});
|
||||
```
|
||||
|
||||
<h2 id="inherit" lay-toc="{hot: true}">继承</h2>
|
||||
|
||||
通过 `component` 模块创建的组件，均会继承内部定义的基础对外接口和渲染时的通用选项。
|
||||
|
||||
### 1. 组件继承的基础接口：
|
||||
通过 `component` 模块创建的组件，均会继承内部定义的「基础对外接口」和「组件渲染的通用选项」。
|
||||
|
||||
| 接口 | 描述 |
|
||||
| --- | --- |
|
||||
| component.render(options) | 组件渲染 |
|
||||
| component.reload(id, options) | 组件重载 |
|
||||
| component.set(options) | 设置组件渲染时的全局配置项 |
|
||||
| component.on('event(filter)', callback) | 组件的自定义事件 |
|
||||
| component.getThis(id) | 获取指定组件的实例对象 |
|
||||
| [component.render(options)](#render) | 组件渲染 |
|
||||
| [component.reload(id, options)](#reload) | 组件重载 |
|
||||
| [component.set(options)](#set) | 设置组件渲染时的全局配置项 |
|
||||
| [component.on(\'event(filter)\', callback)](#on) | 组件的自定义事件 |
|
||||
| [component.getThis(id)](#getThis) | 获取指定组件的实例对象 |
|
||||
| component.index | 获得组件的自增索引 |
|
||||
| component.config | 获得组件渲染时的全局配置项。一般通过 `set` 方法设置 |
|
||||
| component.CONST | 获得组件的通用常量集。如 `MOD_NAME` 等 |
|
||||
| component.cache | 获得组件的缓存数据集。如组件实例 ID 集 |
|
||||
| component.Class | 获得组件的构造函数。一般用于扩展原型方法 |
|
||||
| [component.CONST](#CONST) | 获得组件的通用常量集。如 `MOD_NAME` 等 |
|
||||
| [component.Class](#Class) | 获得组件的构造函数。一般用于扩展原型方法 |
|
||||
|
||||
除此之外，你也可以对接口进行任意扩展，如：
|
||||
> 注：上表中的 `component` 为组件的基础对象，实际使用时，请根据实组件名称进行替换。如 `tabs` 组件，对应的接口则为：`tabs.render(options)` `tabs.on('event(filter)', callback)` 等。
|
||||
|
||||
<h3 id="render" lay-toc="{level: 2}">组件渲染</h3>
|
||||
|
||||
`component.render(options)`
|
||||
|
||||
- 参数 `options` : 组件渲染的配置项。可继承的通用选项见下表：
|
||||
|
||||
| 选项 | 描述 |
|
||||
| --- | --- |
|
||||
| elem | 组件渲染指定的目标元素 |
|
||||
| id | 组件渲染的唯一实例 ID |
|
||||
| show | 是否初始即渲染组件。通常结合创建组件设定的 `isRenderOnEvent` 选项决定是否启用 |
|
||||
|
||||
更多渲染时的选项则由各组件内部单独定义，具体可查阅各组件对应的文档。
|
||||
|
||||
```js
|
||||
// 以 tabs 组件为例
|
||||
// 渲染
|
||||
tabs.render({
|
||||
elem: '#id',
|
||||
// …
|
||||
});
|
||||
```
|
||||
|
||||
<h3 id="reload" lay-toc="{level: 2}">组件重载</h3>
|
||||
|
||||
`component.reload(id, options)`
|
||||
|
||||
- 参数 `id` : 组件实例 ID。
|
||||
- 参数 `options` : 组件重载的配置项。
|
||||
|
||||
该方法可实现对组件的完整重载。部分组件通常还提供了「仅数据重载」，具体可参考各组件对应的文档。
|
||||
|
||||
```js
|
||||
// 以 tabs 组件为例
|
||||
// 重载 tabs 组件实例
|
||||
tabs.reload('id', {
|
||||
// …
|
||||
})
|
||||
```
|
||||
|
||||
<h3 id="set" lay-toc="{level: 2}">全局设置</h3>
|
||||
|
||||
`component.set(options)`
|
||||
|
||||
- 参数 `options` : 组件渲染的配置项。
|
||||
|
||||
该方法用于全局设置组件渲染时的默认配置项，需在组件渲染之前执行。
|
||||
|
||||
```js
|
||||
// 以 tabs 组件为例
|
||||
// 全局设置。后续所有渲染均会生效，除非对选项进行覆盖
|
||||
tabs.set({
|
||||
trigger: 'mouseenter' // 默认的触发事件
|
||||
// …
|
||||
});
|
||||
|
||||
// 渲染实例 1
|
||||
tabs.render({ id: 'id1'}); // 继承全局设置
|
||||
|
||||
// 渲染实例 2
|
||||
tabs.render({
|
||||
id: 'id2',
|
||||
trigger: 'click' // 覆盖全局的触发事件
|
||||
});
|
||||
```
|
||||
|
||||
<h3 id="on" lay-toc="{level: 2}">事件定义</h3>
|
||||
|
||||
`component.on('event(id)', callback)`
|
||||
|
||||
- 参数 `event(id)` : 是事件的特定结构。 `event` 为事件名，支持的事件见下表。`id` 为组件的实例 ID。
|
||||
- 参数 `callback` : 事件回调函数。返回的参数由各组件内部单独定义。
|
||||
|
||||
具体事件一般由组件内部单独定义，具体可查看各组件对应的文档。
|
||||
|
||||
```js
|
||||
// 以 tabs 组件为例：
|
||||
// 组件渲染成功后的事件
|
||||
tabs.on('afterRender(id)', function(data) {
|
||||
console.log(obj);
|
||||
});
|
||||
```
|
||||
|
||||
<h3 id="getThis" lay-toc="{level: 2}">获取实例</h3>
|
||||
|
||||
`component.getThis(id)`
|
||||
|
||||
- 参数 `id` : 组件的实例 ID。
|
||||
|
||||
该方法可获取组件渲染时对应的实例，以调用组件内部的原型方法，一般用于在外部对组件进行扩展或重构。
|
||||
|
||||
```js
|
||||
// 以 tabs 组件为例
|
||||
var tabInstance = tabs.getThis('id');
|
||||
// 调用内部的标签滚动方法
|
||||
tabInstance.roll();
|
||||
```
|
||||
|
||||
<h3 id="CONST" lay-toc="{level: 2}">基础常量</h3>
|
||||
|
||||
`component.CONST`
|
||||
|
||||
获取组件的通用常量集，一般存放固定字符，如类名等。
|
||||
|
||||
```js
|
||||
// 基础常量如下
|
||||
component.CONST.MOD_NAME; // 组件名称
|
||||
component.CONST.MOD_INDEX; // 组件自增索引
|
||||
component.CONST.CLASS_THIS; // layui-this
|
||||
component.CONST.CLASS_SHOW; // layui-show
|
||||
component.CONST.CLASS_HIDE; // layui-hide
|
||||
component.CONST.CLASS_HIDEV; // layui-hide-v
|
||||
component.CONST.CLASS_DISABLED; // layui-disabled
|
||||
component.CONST.CLASS_NONE; // layui-none
|
||||
|
||||
// 更多常量一般在各组件内部单独定义，以 tabs 组件为例
|
||||
tabs.CONST.ELEM; // layui-tabs
|
||||
```
|
||||
|
||||
<h3 id="extend" lay-toc="{level: 2}">扩展接口</h3>
|
||||
|
||||
除上述「基础接口」外，你也可以对接口进行任意扩展，如：
|
||||
|
||||
```js
|
||||
/**
|
||||
|
|
@ -138,17 +233,55 @@ layui.use('test', function() {
|
|||
});
|
||||
```
|
||||
|
||||
### 2. 组件渲染时继承的通用选项：
|
||||
<h3 id="Class" lay-toc="{level: 2}">扩展原型</h3>
|
||||
|
||||
| 选项 | 描述 |
|
||||
| --- | --- |
|
||||
| elem | 组件渲染指定的目标元素 |
|
||||
| id | 组件渲染的唯一索引 |
|
||||
| show | 是否初始即渲染组件。通常结合创建组件设定的 `isRenderOnEvent` 选项决定是否启用 |
|
||||
`component.Class`
|
||||
|
||||
除此之外，其他渲染时的配置选项则由各自的组件内部单独定义。
|
||||
通过获得组件的构造函数，可对组件的原型进行重构，但一般不推荐，因为这可能破坏组件的基础功能。
|
||||
|
||||
```
|
||||
// 以 tabs 组件为例
|
||||
var tabs = layui.tabs;
|
||||
|
||||
// 获得 tabs 组件构造函数
|
||||
var Class = tabs.Class;
|
||||
|
||||
// 重构 tabs 组件内部的 xxx 方法（不推荐）
|
||||
Class.prototype.xxx = function() {
|
||||
// …
|
||||
};
|
||||
```
|
||||
|
||||
当然，如果是通过 `layui.component()` 方法创建一个新的组件，通常必须借助 `Class` 构造函数扩展组件原型，以灵活实现组件的个性化定制。但一般不推荐重写 `component.js` 原型中已经定义的基础方法，如：`init, reload, cache`
|
||||
|
||||
```
|
||||
/**
|
||||
* 定义组件
|
||||
*/
|
||||
layui.define('component', function(exports) {
|
||||
// 创建组件
|
||||
var component = layui.component({
|
||||
name: '', // 组件名称
|
||||
// …
|
||||
});
|
||||
|
||||
// 获取构造器
|
||||
var Class = component.Class;
|
||||
|
||||
// 扩展原型
|
||||
Class.prototype.xxx = function() {
|
||||
// …
|
||||
};
|
||||
Class.prototype.aaa = function() {
|
||||
// …
|
||||
};
|
||||
|
||||
// 输出组件接口
|
||||
exports(component.CONST.MOD_NAME, component);
|
||||
});
|
||||
```
|
||||
|
||||
## 💖 心语
|
||||
|
||||
Layui 由于早前欠缺统筹性思维，很多组件自成一体，使得无法对组件进行很好的统一管理。随着版本的迭代，我们也在努力尝试改善这一问题，但很多时候，为了向下兼容而又不得不保留许多旧有的特性。`component` 模块的初衷正是为了确保组件的一致性，如核心逻辑和 API 设计，尽管它的出现时机已经显得有些过晚，但也算是为 2.x 系列版本尽可能地减少些遗憾吧。
|
||||
Layui 由于早前欠缺统筹性思维，很多组件自成一体，使得无法对组件进行很好的统一管理。随着版本的迭代，我们也一直在努力尝试改善这一问题，但很多时候，为了向下兼容而不得不保留许多旧有的特性。`component` 模块的初衷正是为了确保组件的一致性，如核心逻辑和 API 设计等，其目的也是为了让 2.x 系列版本尽可能地减少些遗憾，让 Layui 始终拥有自己的范式。
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue