diff --git a/docs/.layui/index.md b/docs/.layui/index.md index 10045b78..ff751287 100644 --- a/docs/.layui/index.md +++ b/docs/.layui/index.md @@ -2,10 +2,10 @@ title: 某某组件 MOD_NAME toc: true --- - + # 某某组件 -> 某某组件 `MOD_NAME` +> 某某组件 `MOD_NAME`

示例

@@ -27,8 +27,8 @@ toc: true - 参数 `options` : 基础属性配置项。[#详见属性](#options) -

属性

+

属性

{{- d.include("/MOD_NAME/detail/options.md") }} -
\ No newline at end of file + diff --git a/docs/component/detail/options.md b/docs/component/detail/options.md new file mode 100644 index 00000000..8fc24b5b --- /dev/null +++ b/docs/component/detail/options.md @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
属性名描述类型默认值
name + +组件名称。如 `name:'tabs'`，那么在使用组件时，可通过 `layui.tabs` 获得该组件。注：*组件名必须唯一*。 + +string-
config + +定义组件渲染时的默认配置项。 + +object-
CONST + +通用常量集，一般存放固定字符，如类名等。如： + +``` +CONST: { + ELEM: 'layui-tabs', +} +``` + +上述常量可通过 `component.CONST.ELEM` 获得。 + +object-
isRenderWithoutElem + +渲染是否无需指定目标元素。即无需设置 `elem` 选项，一般用于渲染即显示的组件类型。 + +boolean + +`false` + +
isRenderOnEvent + +渲染是否仅由事件触发。如 `dropdown` 这类通过点击触发的组件，那么应该设置为 `true`；而诸如 `tabs` 这类初始即展示的组件，则应该设置为 `false`。*推荐根据组件类型始终显式设置对应值*。 + +boolean + +`true` + +
isDeepReload + +组件重载时是否允许为深度重载，即每次重载时选项进行深度合并。 + +boolean + +`false` + +
+ +
+ +[回调函数](#options.callback) + +
+ +
render + +组件渲染的逻辑。 + +```js +render: function() { + // 组件的容器构建、插入等 + // … +} +``` + +也可以通过原型 `component.Class.prototype.render` 进行定义。 + +
beforeInit + +组件初始化之前的回调函数。 + +```js +beforeInit: function(options) { + console.log(options); // 获得组件初始化前的配置项 +} +``` + +
beforeRender + +渲染之前的回调函数。 + +```js +beforeRender: function(options) { + console.log(options); // 获得组件渲染前的配置项 +} +``` + +
extendsInstance + +扩展组件渲染的实例对象的回调函数。如： + +```js +extendsInstance: function(that) { + return { + // 关闭组件 + close: function() { + that.remove(); // 调用组件原型中的 remove 方法 + } + } +} +``` + +那么，当组件渲染时，即可通过它返回的对象调用实例方法： + +```js +var inst = xxx.render(); // 某组件渲染 +inst.close(); // 关闭某组件 +``` + +
events + +定义组件各类内部事件。 + +```js +events: function() { + // 亦可包含针对组件的 window, document 等全局事件 + // … +} +``` + +也可以通过原型 `component.Class.prototype.events` 进行定义。 + +
diff --git a/docs/component/index.md b/docs/component/index.md new file mode 100644 index 00000000..31081b53 --- /dev/null +++ b/docs/component/index.md @@ -0,0 +1,154 @@ +--- +title: 组件构建器 component +toc: true +--- + +# 组件构建器 2.10+ + +> 组件构建器 `component` 是 2.10 版本新增的重要模块，旨在为 Layui 2 系列版本逐步构建统一 API 规范的组件。 + +

API

+ +| API | 描述 | +| --- | --- | +| [layui.component(options)](#create) | 创建组件 | + +

创建组件

+ +`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); +}); +``` + +

属性配置

+ +
+{{- d.include("/component/detail/options.md") }} +
+ +

原型

+ +创建组件时的 `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); +}); +``` + +

继承

+ +通过 `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 系列版本尽可能地减少些遗憾吧。 +