mirror of https://github.com/layui/layui
docs: 添加 component 组件构建器文档
贤心
parent
36e741da47
commit
72acb98173
|
|
@ -27,7 +27,7 @@ toc: true
|
|||
|
||||
- 参数 `options` : 基础属性配置项。[#详见属性](#options)
|
||||
|
||||
<h2 id="options" lay-toc="{level: 2, hot: true}">属性</h2>
|
||||
<h3 id="options" lay-toc="{level: 2, hot: true}">属性</h3>
|
||||
|
||||
<div>
|
||||
{{- d.include("/MOD_NAME/detail/options.md") }}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,197 @@
|
|||
<table class="layui-table">
|
||||
<colgroup>
|
||||
<col width="150">
|
||||
<col>
|
||||
<col width="100">
|
||||
<col width="100">
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>属性名</th>
|
||||
<th>描述</th>
|
||||
<th>类型</th>
|
||||
<th>默认值</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>
|
||||
|
||||
组件名称。如 `name:'tabs'`，那么在使用组件时，可通过 `layui.tabs` 获得该组件。注：*组件名必须唯一*。
|
||||
|
||||
</td>
|
||||
<td>string</td>
|
||||
<td>-</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>config</td>
|
||||
<td>
|
||||
|
||||
定义组件渲染时的默认配置项。
|
||||
|
||||
</td>
|
||||
<td>object</td>
|
||||
<td>-</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>CONST</td>
|
||||
<td>
|
||||
|
||||
通用常量集，一般存放固定字符，如类名等。如：
|
||||
|
||||
```
|
||||
CONST: {
|
||||
ELEM: 'layui-tabs',
|
||||
}
|
||||
```
|
||||
|
||||
上述常量可通过 `component.CONST.ELEM` 获得。
|
||||
|
||||
</td>
|
||||
<td>object</td>
|
||||
<td>-</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>isRenderWithoutElem</td>
|
||||
<td>
|
||||
|
||||
渲染是否无需指定目标元素。即无需设置 `elem` 选项，一般用于渲染即显示的组件类型。
|
||||
|
||||
</td>
|
||||
<td>boolean</td>
|
||||
<td>
|
||||
|
||||
`false`
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>isRenderOnEvent</td>
|
||||
<td>
|
||||
|
||||
渲染是否仅由事件触发。如 `dropdown` 这类通过点击触发的组件，那么应该设置为 `true`；而诸如 `tabs` 这类初始即展示的组件，则应该设置为 `false`。*推荐根据组件类型始终显式设置对应值*。
|
||||
|
||||
</td>
|
||||
<td>boolean</td>
|
||||
<td>
|
||||
|
||||
`true`
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>isDeepReload</td>
|
||||
<td>
|
||||
|
||||
组件重载时是否允许为深度重载，即每次重载时选项进行深度合并。
|
||||
|
||||
</td>
|
||||
<td>boolean</td>
|
||||
<td>
|
||||
|
||||
`false`
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="4" style="text-align: center">
|
||||
|
||||
<div id="options.callback" lay-pid="options" class="ws-anchor">
|
||||
|
||||
[回调函数](#options.callback)
|
||||
|
||||
</div>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>render</td>
|
||||
<td colspan="3">
|
||||
|
||||
组件渲染的逻辑。
|
||||
|
||||
```js
|
||||
render: function() {
|
||||
// 组件的容器构建、插入等
|
||||
// …
|
||||
}
|
||||
```
|
||||
|
||||
也可以通过原型 `component.Class.prototype.render` 进行定义。
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>beforeInit</td>
|
||||
<td colspan="3">
|
||||
|
||||
组件初始化之前的回调函数。
|
||||
|
||||
```js
|
||||
beforeInit: function(options) {
|
||||
console.log(options); // 获得组件初始化前的配置项
|
||||
}
|
||||
```
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>beforeRender</td>
|
||||
<td colspan="3">
|
||||
|
||||
渲染之前的回调函数。
|
||||
|
||||
```js
|
||||
beforeRender: function(options) {
|
||||
console.log(options); // 获得组件渲染前的配置项
|
||||
}
|
||||
```
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>extendsInstance</td>
|
||||
<td colspan="3">
|
||||
|
||||
扩展组件渲染的实例对象的回调函数。如：
|
||||
|
||||
```js
|
||||
extendsInstance: function(that) {
|
||||
return {
|
||||
// 关闭组件
|
||||
close: function() {
|
||||
that.remove(); // 调用组件原型中的 remove 方法
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
那么，当组件渲染时，即可通过它返回的对象调用实例方法：
|
||||
|
||||
```js
|
||||
var inst = xxx.render(); // 某组件渲染
|
||||
inst.close(); // 关闭某组件
|
||||
```
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>events</td>
|
||||
<td colspan="3">
|
||||
|
||||
定义组件各类内部事件。
|
||||
|
||||
```js
|
||||
events: function() {
|
||||
// 亦可包含针对组件的 window, document 等全局事件
|
||||
// …
|
||||
}
|
||||
```
|
||||
|
||||
也可以通过原型 `component.Class.prototype.events` 进行定义。
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
@ -0,0 +1,154 @@
|
|||
---
|
||||
title: 组件构建器 component
|
||||
toc: true
|
||||
---
|
||||
|
||||
# 组件构建器 <sup>2.10+</sup>
|
||||
|
||||
> 组件构建器 `component` 是 2.10 版本新增的重要模块，旨在为 Layui 2 系列版本逐步构建统一 API 规范的组件。
|
||||
|
||||
<h2 id="api" lay-toc="{}">API</h2>
|
||||
|
||||
| API | 描述 |
|
||||
| --- | --- |
|
||||
| [layui.component(options)](#create) | 创建组件 |
|
||||
|
||||
<h3 id="create" lay-toc="{hot: true, level: 2}">创建组件</h3>
|
||||
|
||||
`layui.component(options);`
|
||||
|
||||
- 参数 `options` : 基础属性配置项。[#详见属性](#options)
|
||||
|
||||
该方法返回一个对象，通常用于当前组件的基础对外接口，如：组件渲染、重载、事件操作，及构造函数等等。用法示例：
|
||||
|
||||
```js
|
||||
/**
|
||||
* tabs
|
||||
* 标签页组件
|
||||
*/
|
||||
layui.define('component', function(exports) {
|
||||
// 创建组件
|
||||
var component = layui.component({
|
||||
name: 'tabs', // 组件名称
|
||||
config: {}, // 组件默认配置项
|
||||
render: function() {
|
||||
// 组件渲染逻辑
|
||||
// …
|
||||
},
|
||||
// 其他选项
|
||||
});
|
||||
|
||||
// 将创建组件时返回的 `component` 对象作为组件的接口输出
|
||||
// 接口将继承基础成员，如 render, reload, set 等方法
|
||||
exports(component.CONST.MOD_NAME, component);
|
||||
});
|
||||
```
|
||||
|
||||
<h3 id="options" lay-toc="{level: 2, hot: true}">属性配置</h3>
|
||||
|
||||
<div>
|
||||
{{- d.include("/component/detail/options.md") }}
|
||||
</div>
|
||||
|
||||
<h2 id="prototype" lay-toc="{hot: true}">原型</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.render(options) | 组件渲染 |
|
||||
| component.reload(id, options) | 组件重载 |
|
||||
| component.set(options) | 设置组件渲染时的全局配置项 |
|
||||
| component.on('event(filter)', callback) | 组件的自定义事件 |
|
||||
| component.getThis(id) | 获取指定组件的实例对象 |
|
||||
| component.index | 获得组件的自增索引 |
|
||||
| component.config | 获得组件渲染时的全局配置项。一般通过 `set` 方法设置 |
|
||||
| component.CONST | 获得组件的通用常量集。如 `MOD_NAME` 等 |
|
||||
| component.cache | 获得组件的缓存数据集。如组件实例 ID 集 |
|
||||
| component.Class | 获得组件的构造函数。一般用于扩展原型方法 |
|
||||
|
||||
除此之外，你也可以对接口进行任意扩展，如：
|
||||
|
||||
```js
|
||||
/**
|
||||
* 定义组件
|
||||
*/
|
||||
layui.define('component', function(exports) {
|
||||
// 创建组件
|
||||
var component = layui.component({
|
||||
name: 'test',
|
||||
// …
|
||||
});
|
||||
// 扩展组件接口
|
||||
layui.$.extend(component, {
|
||||
// 以扩展一个关闭组件面板的接口为例
|
||||
close: function(id) {
|
||||
var that = component.getThis(id);
|
||||
if(!that) return this;
|
||||
that.remove(obj); // 调用原型中的 remove 方法
|
||||
}
|
||||
});
|
||||
// 输出组件接口
|
||||
exports(component.CONST.MOD_NAME, component);
|
||||
});
|
||||
```
|
||||
|
||||
```js
|
||||
/**
|
||||
* 使用组件（以上述定义的 test 组件为例）
|
||||
*/
|
||||
layui.use('test', function() {
|
||||
var test = layui.test;
|
||||
// 渲染组件
|
||||
test.render({
|
||||
elem: '#id',
|
||||
id: 'test-1'
|
||||
});
|
||||
// 关闭组件面板（通常在某个事件中使用）
|
||||
test.close('test-1');
|
||||
});
|
||||
```
|
||||
|
||||
### 2. 组件渲染时继承的通用选项：
|
||||
|
||||
| 选项 | 描述 |
|
||||
| --- | --- |
|
||||
| elem | 组件渲染指定的目标元素 |
|
||||
| id | 组件渲染的唯一索引 |
|
||||
| show | 是否初始即渲染组件。通常结合创建组件设定的 `isRenderOnEvent` 选项决定是否启用 |
|
||||
|
||||
除此之外，其他渲染时的配置选项则由各自的组件内部单独定义。
|
||||
|
||||
## 💖 心语
|
||||
|
||||
Layui 由于早前欠缺统筹性思维，很多组件自成一体，使得无法对组件进行很好的统一管理。随着版本的迭代，我们也在努力尝试改善这一问题，但很多时候，为了向下兼容而又不得不保留许多旧有的特性。`component` 模块的初衷正是为了确保组件的一致性，如核心逻辑和 API 设计，尽管它的出现时机已经显得有些过晚，但也算是为 2.x 系列版本尽可能地减少些遗憾吧。
|
||||
|
||||
Loading…
Reference in New Issue