From 72acb9817317c12799cc34ebb328636a26623aa6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B4=A4=E5=BF=83?=
<3277200+sentsim@users.noreply.github.com>
Date: Sun, 23 Feb 2025 16:00:55 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20component=20?=
=?UTF-8?q?=E7=BB=84=E4=BB=B6=E6=9E=84=E5=BB=BA=E5=99=A8=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/.layui/index.md | 8 +-
docs/component/detail/options.md | 197 +++++++++++++++++++++++++++++++
docs/component/index.md | 154 ++++++++++++++++++++++++
3 files changed, 355 insertions(+), 4 deletions(-)
create mode 100644 docs/component/detail/options.md
create mode 100644 docs/component/index.md
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 系列版本尽可能地减少些遗憾吧。
+