- 1. 概述
- 2. 组件加载机制
- 3. 组件功能及应用场景
- 3.1 CompDebug
- 3.2 CompLayout
- 3.3 CompRichText
- 3.4 CompTimeDown
- 3.5 CompSchedule
- 3.6 CompToggle
- 3.7 CompTextUnderLine
- 3.8 CompSpineAction
- 3.9 CompAutoScaleToWidth
- 3.10 CompTextOverflow
- 3.11 CompCloseShield
- 3.12 CompEditBox
- 3.13 CompPickerView
- 3.14 CompLazyList
- 3.15 CompScrollBar
- 3.16 CompActionCustom
- 3.17 CompTouchListener
- 3.18 CompMusicEffect
- 3.19 CompMask
- 3.20 CompTouchLayer
- 3.21 CompRedPoint & CompRedPointManager
- 4. 组件扩展开发
- 5. 组件依赖工具函数
LuaComponent 是一个基于 Cocos 节点系统的自定义组件系统，为宿主节点提供多样化的服务能力。每个组件代表一种特定的功能服务，宿主节点可以根据需求添加多个不同的组件。需要注意的是，同一个宿主节点中不能存在同名组件。
目前组件只支持通过代码方式加载，暂不支持编辑器操作。所有组件已在 cc.ext 命名空间中声明，可直接使用 cc.ext.compXXX。
组件通过以下两种方法加载：
addLuaComponent：添加组件（如已存在同名组件，会先清除再添加）tryAddLuaComponent：尝试添加组件（如已存在同名组件，则不再重复添加）
组件参数请查看实现代码，每个组件init参数都有注释。
-- 添加 CompLayout 组件示例
node:addLuaComponent(cc.ext.CompLayout, {
alignment = CompLayout.AlignmentEnum.RightToLeft,
spacing = 80
})
-- 或使用 tryAddLuaComponent
node:tryAddLuaComponent(cc.ext.CompLayout, {
alignment = CompLayout.AlignmentEnum.RightToLeft,
spacing = 80
})组件的操作 API 基于扩展后的 Cocos 节点 API，主要包括：
-- 获取组件
function Node:getLuaComponent(componentName)
end
-- 添加组件（如已存在同名组件，则不再重复添加）
function Node:tryAddLuaComponent(component, params)
end
-- 添加组件（如已存在同名组件，会先清除再次添加）
function Node:addLuaComponent(component, params)
end全部API详见CocosExtend.lua
某些组件可能只支持特定类型的宿主节点，具体要求需查看组件的实现代码。
通过组件的 dependType 方法可以确定所需的宿主节点类型：
function Component:dependType()
return ... -- 返回指定的宿主节点类型
end调试组件，用于显示组件的包围盒。
- 支持设置包围盒线条颜色、粗细
应用场景：需要查看节点实际包围盒范围时使用
自动布局组件，对宿主节点的子节点进行自动排列。
- 支持单行排列和网格排列
- 支持边缘间距和锚点间距
- 支持子节点显示、隐藏、透明度变化、新增、删除等情况时自动排列
- 支持整体水平居中
- 支持自动刷新间隔（默认每帧刷新）
- 支持手动刷新模式
应用场景： 例1：大厅一排按钮，如使用边缘间距，点击按钮后产生缩放效果，缩放的同时会影响其他按钮的位置，因为组件需要保证每帧边缘间距都是一样的。这种情况下使用锚点间距就不会有这个问题。 边缘间距可以保证节点不重叠，锚点间距则可以保证子节点位置固定 例2：(图标+文字)需要整体居中
Html标签样式富文本组件，功能与 Cocos Creator 的 RichText 组件类似，略微添加了些许功能。 https://docs.cocos.com/creator/manual/zh/ui-system/components/editor/richtext.html?h=richtext
- 支持的样式：颜色（color）、字体（font）、字体大小（size）、字体描边（outline）、加粗（b）、斜体（i）、下划线（u）、换行（br）、图片（img）和点击事件（on）
- 支持标签嵌套
倒计时组件，提供多样化的倒计时功能。
- 支持时间戳格式倒计时（切后台不影响）
- 支持秒数倒计时（切后台会影响）
- 支持文本模式匹配
- 支持外部传入基准时间
应用场景：
- 活动限时抢购倒计时显示
- 比赛准备阶段倒计时提示
计时组件，提供无界面的计时功能。
单选框 Tab 组件，支持在编辑器中完成状态预览。
- 支持 Tab 组内选中切换的自动状态管理
- 可与 CompMusicEffect 组件联动
文本下划线组件，适用于需要下划线效果的文字。
Spine 动画转换组件，将 Spine 动画数据转换为 Cocos 可解析的格式。 解析后可直接播放，亦可在Spine动画中挂点。
- 支持解析位移、缩放、旋转、颜色、透明度等动画属性
- 支持指定动画名称和播放帧区间
- 支持动画速率修改
- 支持动画循环和回调
- 支持动画缓存
- 支持修改动画关键帧数据
应用场景：需要程序手写的动画代码，理论上都可以通过这个解析后使用
限宽组件，自动控制节点的最大宽度。
- 超过限定宽度时自动缩小至最大宽度
- 未超过限定宽度时保持原始比例 注：本组件会自动缩放宿主节点，因此添加本组件后，可能导致手动操作缩放宿主节点的功能失效。
文本溢出处理组件，优化长文本显示。
- 当宿主宽度超过限定值时，会最大可能显示全文本信息。
- 超出部分以省略号...结尾，也可选择直接截断 注：本组件会自动缩放宿主节点，因此添加本组件后，可能导致手动操作缩放宿主节点的功能失效。
屏蔽层组件，用于处理点击关闭事件。
- 支持点击后自动关闭
- 支持自定义关闭行为
应用场景：游戏内的部分tips浮层，一般显示后需要点击全屏关闭等，无需再手动添加节点和代码，加入此组件即可
扩展的输入框组件，对 Cocos 原生 EditBox 进行增强。
- 支持单行/多行文本
- 支持 UTF8 字数限制，超过即截断
- 支持预设文本定制
- 支持文本对齐方式设置
- 提供输入焦点和完成回调
单元拾取器组件，类似 iOS 的时间选取器。
- 适用于时间日期选择、局数选择等场景
惰性更新组件，适用于列表型界面优化。
- 支持配置分帧加载、自动分帧加载
- 支持节点缓存
- 支持刷新完成回调
应用场景：
- 列表数量不是特别大的情况，对于分帧加载仍未能满足需求的情况，建议采用虚拟列表cc.tableView
- 虚拟列表cc.tableView的单元项，如果存在异步操作，复用节点变换后很可能引入异步bug。
- 如果单元项不是很多，建议使用CompLazyList，更简单直观。如果单元项很多，建议采用虚拟列表cc.tableView，但要注意异步操作。
自定义滚动条组件，用于美化滚动列表。
自定义动画组件，支持数值变化动画。
- 支持三阶贝塞尔曲线缓动
- 支持自定义数值更新回调
应用场景：
- 比如5秒内数值以正弦曲线的形式由0增加到1，每帧调用回调函数
点击事件组件，提供统一的点击处理。
- 支持点击效果定制（缩放、颜色）
- 支持点击音效定制
- 支持连续点击 CD 设置
音效组件，可独立使用或与其他组件配合。
遮罩组件，提供便捷的遮罩效果处理。
- 注意：会修改宿主节点的父节点关系
滑动组件，用于检测滑动手势。
- 支持水平/垂直方向滑动检测
- 支持滑动距离和速度判定
红点组件，用于管理功能红点显示。
- 支持多标签组合判定
- 支持即时刷新
- 扩展组件主要关注
Component.lua和CocosExtend.lua这两个文件 - 组件不仅限于 UI 组件，也可以是通用业务功能组件
- 组件属性支持类 JS 方式声明，可参考 CompRichText 的实现方式
框架提供了一系列实用的工具函数，这些函数被组件系统广泛使用：
-- 字符串查找
string.indexOf(s, pattern, init, plain)
string.lastIndexOf(s, pattern, init, plain)
string.matchMulti(s, reg)
string.startsWith(s, pattern, init, plain)
string.endsWith(s, searchValue)
-- 正则测试
string.testRegExp(regExp, s)
-- UTF8 操作
string.utf8Sub(s, startIndex, endIndex)
string.utf8Len(s)
-- Unicode 操作
string.unicodeCharAt(s, index)
string.unicodeLength(s)
string.unicodeCharTable(s)-- 节点查找
cc.find(path, referenceNode)
-- 节点树打印
cc.printNodeTree(rootNode, description, pattern, nesting)
-- 节点操作
Node:setDebug(showBoundBox)
Node:isNull()
Node:setWidth(width)
Node:setHeight(height)
Node:getWidth()
Node:getHeight()
-- 延迟执行
Node:performWithDelay(callback, delay)
-- 事件处理
Node:on(eventID, callback)
Node:off(handle)
-- 位置转换
Node:getPositionWorld()
Node:setPositionWorld(worldPosition)
-- 节点置灰/触摸跟随置灰开关
Node:setGrayedAndEnabled(isGray, affectTouch)