组件：宫格框

宫格框组件用于以网格（Grid）布局方式展示项目集合，支持自定义列间距、行间距、对齐方式等，并通过回调函数让开发者自定义每个格子的渲染内容。它类似于一个可自定义的网格容器，适合展示图标菜单、图片墙、功能入口、卡片集合等需要整齐排列的场景。宫格框会自动根据容器宽度和项目数量计算每行显示的列数（由项目宽度决定），并提供滚动支持。

典型使用场景：

应用首页功能入口（九宫格菜单）
图片/视频缩略图墙（相册、作品集）
商品或卡片网格展示（电商、内容聚合）
工具或功能选择面板（设置项、快捷操作）

📌 继承自视图的成员速查

本组件继承自 视图 类，可直接使用以下属性和方法：

属性： ID、左边、顶边、右边、底边、宽度、高度、背景、背景颜色、背景图像、文本、文本颜色、字体、字体大小、字体粗细、行高、边框、边框圆角、边框宽度、光标样式、显示模式、透明度、外边距、外边距底、外边距左、外边距右、外边距顶、最大高度、最大宽度、最小高度、最小宽度、内边距、内边距底、内边距左、内边距右、内边距顶、定位、CLASS、InnerHTML、OuterHTML、内容水平对齐方式、首行缩进、可视、显示层级、内联样式、禁用

方法： 追加内联样式(样式文本)、置内联样式(名称,值)、取内联样式值(名称)、取Style对象()、添加事件(事件名称, 回调函数)、删除事件(事件名称, 回调函数)、获取焦点()、清除焦点()、添加样式类(类名称)、移除样式类(类名称)、取样式类列表()、取样式类()、执行单击()、取属性值(属性名)、取属性节点(属性名)、取布局参数()、取渲染宽度()、取渲染高度()、取渲染顶边()、取渲染左边()、左侧对齐到(目标组件,偏移量)、右侧对齐到(目标组件,偏移量)、顶边对齐到(目标组件,偏移量)、底边对齐到(目标组件,偏移量)、右侧对齐到左(目标组件, 偏移量)、左侧对齐到右(目标组件, 偏移量)、底边对齐到顶(目标组件, 偏移量)、顶边对齐到底(目标组件, 偏移量)、有指定属性(属性名)、有属性()、内容可编辑()、包含CSS类(类名)、取命名空间()、取下个节点()、取下个元素()、取节点名称()、取节点类型()、取父节点()、取父元素()、取上个节点()、取上个元素()、销毁()、删除属性(属性名)、删除属性节点(属性名)、置属性值(属性名, 属性值)、置属性节点(属性节点)、取标签名()、移动(左边顶边, 宽度, 高度)、取原生对象()、置被单击回调(回调函数)、置被双击回调(回调函数)、置鼠标被进入回调(回调函数)、置鼠标被移出回调(回调函数)、置鼠标被移动回调(回调函数)、置鼠标被按下回调(回调函数)、置鼠标被抬起回调(回调函数)、置鼠标滚轮被滚动回调(回调函数)、置键盘被按下回调(回调函数)、置按键被抬起回调(回调函数)、置按键被压下回调(回调函数)、置被失去焦点回调(回调函数)、置被获得焦点回调(回调函数)

事件： 被单击(源对象,事件源)、被双击(源对象,事件源)、鼠标被进入(源对象,事件源)、鼠标被移出(源对象,事件源)、鼠标被移动(源对象,事件源)、鼠标被按下(源对象,事件源)、鼠标被抬起(源对象,事件源)、鼠标滚轮被滚动(源对象,事件源)、键盘被按下(源对象,事件源)、按键被抬起(源对象,事件源)、按键被压下(源对象,事件源)、被失去焦点(源对象,事件源)、被获得焦点(源对象,事件源)

💡 完整成员列表及详细说明请参考：视图 类

常用操作速查

操作	属性/方法	示例
设置是否拉伸内容（隐藏滚动条）	`拉伸内容`	`宫格框1.拉伸内容 = 真`
设置列间距	`列间距`	`宫格框1.列间距 = 12`
设置行间距	`行间距`	`宫格框1.行间距 = 16`
设置横向对齐方式	`横向对齐方式`	`宫格框1.横向对齐方式 = "space-between"`
设置纵向对齐方式	`纵向对齐方式`	`宫格框1.纵向对齐方式 = "center"`
设置内容整体对齐方式	`内容整体对齐方式`	`宫格框1.内容整体对齐方式 = "center"`
添加单个项目	`添加项目(项目对象)`	`宫格框1.添加项目({标题:"设置", 图标:"icon.png"})`
批量添加项目	`添加项目集(项目对象数组)`	`宫格框1.添加项目集([{...}, {...}])`
插入项目	`插入项目(索引, 项目对象)`	`宫格框1.插入项目(0, {标题:"置顶"})`
删除项目	`删除项目(索引)`	`宫格框1.删除项目(2)`
更新项目	`更新项目(索引, 项目对象)`	`宫格框1.更新项目(1, {标题:"新名称"})`
获取所有项目	`取项目集合()`	`变量全部 = 宫格框1.取项目集合()`
获取项目数量	`取项目数()`	`变量数量 = 宫格框1.取项目数()`
清空所有项目	`清空()`	`宫格框1.清空()`
触发渲染	`渲染()`	`宫格框1.渲染()`
自定义每个格子的渲染	`置请求加载项目回调(回调函数)`	`宫格框1.置请求加载项目回调((集合, 索引) => { ... 返回组件 ... })`

样式美化参考

宫格框的外观主要通过继承的视图属性以及专用对齐属性调整：

整体容器：设置 宽度、高度、背景颜色、边框、边框圆角 等控制整体样式。
项目间距：通过 列间距 和 行间距 控制格子之间的间隔。
对齐控制：
- 横向对齐方式：控制每行内项目在水平方向上的分布（左对齐、居中、两端分散等）。
- 纵向对齐方式：控制项目在垂直方向上的对齐（顶部、居中、底部、拉伸等）。
- 内容整体对齐方式：控制多行项目作为一个整体在容器垂直方向上的对齐。
内容拉伸：当 拉伸内容 = 真 时，宫格框高度自适应所有项目总高度，不显示滚动条；为 假（默认）时，超出高度出现滚动条。
项目渲染：在回调中返回任意视图组件，可自由组合图文、按钮、图标等，实现高度定制化。

基础示例

创建一个简单的功能菜单宫格，每个项目显示图标和文字。

变量 宫格框1 = 创建 宫格框()
宫格框1.左边 = 50
宫格框1.顶边 = 50
宫格框1.宽度 = 400
宫格框1.高度 = 300
宫格框1.列间距 = "12px"
宫格框1.行间距 = "12px"
宫格框1.横向对齐方式 = "center"
宫格框1.纵向对齐方式 = "center"

' 准备数据
变量 数据 = [
    {标题: "音乐", 图标: "🎵"},
    {标题: "视频", 图标: "🎬"},
    {标题: "图片", 图标: "🖼️"},
    {标题: "文档", 图标: "📄"},
    {标题: "设置", 图标: "⚙️"},
    {标题: "帮助", 图标: "❓"}
]
宫格框1.添加项目集(数据)

' 自定义渲染回调
宫格框1.置请求加载项目回调((项目集合, 索引) => {
    变量 项 = 项目集合[索引]
    变量 容器 = 创建 弹性布局()
    容器.方向 = "column"
    容器.侧轴对齐 = "center"
    容器.宽度 = 80
    容器.高度 = 80
    容器.背景颜色 = "#f5f5f5"
    容器.边框圆角 = "8px"
    容器.内边距 = "8px"
    
    变量 图标标签 = 创建 标签()
    图标标签.文本 = 项.图标
    图标标签.字体大小 = "32px"
    容器.添加组件(图标标签)
    
    变量 标题标签 = 创建 标签()
    标题标签.文本 = 项.标题
    标题标签.字体大小 = "12px"
    标题标签.文本颜色 = "#333"
    容器.添加组件(标题标签)
    
    返回 容器
})

宫格框1.渲染()
添加组件(宫格框1)

综合示例：应用中心图标墙

本示例模拟一个应用中心界面，展示多个应用图标，每个图标可点击并弹出提示，同时支持动态添加新应用。

' ========== 创建标题 ==========
变量 标题 = 创建 标签()
标题.左边 = 30
标题.顶边 = 20
标题.文本 = "📱 应用中心"
标题.字体大小 = "20px"
标题.字体粗细 = "bold"
添加组件(标题)

' ========== 创建宫格框 ==========
变量 宫格框_应用 = 创建 宫格框()
宫格框_应用.左边 = 30
宫格框_应用.顶边 = 60
宫格框_应用.宽度 = 500
宫格框_应用.高度 = 400
宫格框_应用.背景颜色 = "#ffffff"
宫格框_应用.边框 = "1px solid #e8e8e8"
宫格框_应用.边框圆角 = "12px"
宫格框_应用.内边距 = "16px"
宫格框_应用.列间距 = "16px"
宫格框_应用.行间距 = "16px"
宫格框_应用.横向对齐方式 = "flex-start"
宫格框_应用.纵向对齐方式 = "center"
添加组件(宫格框_应用)

' ========== 准备应用数据 ==========
变量 应用数据 = [
    {名称: "微信", 图标: "💬", 颜色: "#07c160"},
    {名称: "支付宝", 图标: "💰", 颜色: "#1677ff"},
    {名称: "抖音", 图标: "🎵", 颜色: "#000000"},
    {名称: "微博", 图标: "📢", 颜色: "#ff8200"},
    {名称: "淘宝", 图标: "🛒", 颜色: "#ff4400"},
    {名称: "美团", 图标: "🍔", 颜色: "#ffc300"},
    {名称: "携程", 图标: "✈️", 颜色: "#1e90ff"},
    {名称: "百度", 图标: "🔍", 颜色: "#2932e1"}
]
宫格框_应用.添加项目集(应用数据)

' ========== 自定义渲染回调 ==========
宫格框_应用.置请求加载项目回调((项目集合, 索引) => {
    变量 项 = 项目集合[索引]
    
    变量 容器 = 创建 弹性布局()
    容器.方向 = "column"
    容器.侧轴对齐 = "center"
    容器.主轴对齐 = "center"
    容器.宽度 = 90
    容器.高度 = 110
    容器.背景颜色 = "#fafafa"
    容器.边框 = "1px solid #f0f0f0"
    容器.边框圆角 = "12px"
    容器.光标样式 = "pointer"
    容器.内边距 = "8px"
    
    ' 图标圆形背景
    变量 图标容器 = 创建 弹性布局()
    图标容器.方向 = "row"
    图标容器.侧轴对齐 = "center"
    图标容器.主轴对齐 = "center"
    图标容器.宽度 = 56
    图标容器.高度 = 56
    图标容器.背景颜色 = 项.颜色
    图标容器.边框圆角 = "28px"
    容器.添加组件(图标容器)
    
    变量 图标标签 = 创建 标签()
    图标标签.文本 = 项.图标
    图标标签.字体大小 = "28px"
    图标容器.添加组件(图标标签)
    
    ' 应用名称
    变量 名称标签 = 创建 标签()
    名称标签.文本 = 项.名称
    名称标签.字体大小 = "13px"
    名称标签.文本颜色 = "#333"
    名称标签.外边距顶 = "8px"
    容器.添加组件(名称标签)
    
    ' 为每个项目添加点击事件（在容器上绑定）
    容器.置被单击回调((源对象, 事件对象) => {
        ' 注意：这里的源对象是容器本身，我们无法直接获取项数据，
        ' 所以利用闭包捕获索引，但轻语言不支持闭包捕获变量，
        ' 所以我们可以通过数据集合和索引在回调中获取项信息。
        ' 另一种方式是使用组件的数据标签，但这里我们使用全局变量存储当前索引，
        ' 或者直接在事件中通过查找方式获取。
        ' 为简化，使用弹出提示
        变量 当前项 = 项目集合[索引]
        弹出提示("启动应用：" + 当前项.名称)
    })
    
    返回 容器
})

宫格框_应用.渲染()

' ========== 添加新应用按钮 ==========
变量 添加按钮 = 创建 按钮()
添加按钮.左边 = 30
添加按钮.顶边 = 480
添加按钮.宽度 = 120
添加按钮.高度 = 36
添加按钮.文本 = "+ 添加应用"
添加按钮.背景颜色 = "#1890ff"
添加按钮.文本颜色 = "#ffffff"
添加按钮.边框圆角 = "6px"
添加组件(添加按钮)

添加按钮.置被单击回调((源对象, 事件对象) => {
    ' 模拟添加新应用
    变量 新应用 = {
        名称: "新应用" + (宫格框_应用.取项目数() + 1),
        图标: "⭐",
        颜色: "#52c41a"
    }
    宫格框_应用.添加项目(新应用)
    宫格框_应用.渲染()  ' 重新渲染
    弹出提示("已添加新应用")
})

属性详解

拉伸内容

类型： 逻辑型
说明： 设置是否拉伸宫格内容以填满容器高度。当为 真 时，宫格高度由内容撑开，不显示滚动条；当为 假（默认）时，超出 高度 的内容会出现滚动条。

列间距

类型： 数值型
说明： 设置每列项目之间的水平间距，单位为像素，默认为 10。

行间距

类型： 数值型
说明： 设置每行项目之间的垂直间距，单位为像素，默认为 10。

横向对齐方式

类型： 文本型
说明： 设置每行内项目在水平方向上的分布方式。可选值：
- "flex-start"：左对齐
- "flex-end"：右对齐
- "center"：居中对齐
- "space-between"：两端对齐，项目间等距
- "space-around"：项目两侧间隔相等
- "space-evenly"：项目均匀分布，两端与容器边缘距离相等
默认值由组件内部决定（通常为 "flex-start"）。

纵向对齐方式

类型： 文本型
说明： 设置项目在垂直方向上的对齐方式（当项目高度不一致时有效）。可选值：
- "stretch"：拉伸填充（默认）
- "flex-start"：顶部对齐
- "flex-end"：底部对齐
- "center"：居中对齐
- "baseline"：基线对齐

内容整体对齐方式

类型： 文本型
说明： 设置多行项目作为一个整体在容器垂直方向上的对齐方式（当容器高度大于所有项目总高度时有效）。可选值同 横向对齐方式。

函数详解

添加项目(项目对象)

功能： 向数据集合末尾添加一个项目。
参数： 项目对象，可以是任意数据类型（对象、字符串、数字等），推荐对象以便包含多个字段。
返回值： 无。
示例： 宫格框1.添加项目({标题: "新功能", 图标: "icon.png"})

插入项目(索引, 项目对象)

功能： 在指定索引位置插入一个项目。
参数： 索引（数值型，从0开始），项目对象（任意类型）。
返回值： 无。
示例： 宫格框1.插入项目(0, {标题: "置顶项"})

添加项目集(项目对象数组)

功能： 批量添加多个项目到末尾。
参数： 项目对象数组，数组中的每个元素为任意类型。
返回值： 无。
示例： 宫格框1.添加项目集([{标题:"A"}, {标题:"B"}])

插入项目集(索引, 项目对象数组)

功能： 在指定索引位置批量插入多个项目。
参数： 索引（数值型），项目对象数组。
返回值： 无。

删除项目(索引)

功能： 删除指定索引的项目。
参数： 索引（数值型）。
返回值： 无。

更新项目(索引, 项目对象)

功能： 替换指定索引的项目为新数据。
参数： 索引（数值型），项目对象（新数据）。
返回值： 无。

取项目集合()

功能： 获取当前数据集合（数组）。
返回值： 数组，包含所有项目对象。
示例： 变量全部 = 宫格框1.取项目集合()

取项目数()

功能： 获取当前项目数量。
返回值： 数值型。
示例： 变量数量 = 宫格框1.取项目数()

清空()

功能： 清空所有数据，宫格变为空。
返回值： 无。

渲染()

功能： 根据当前数据集合和自定义渲染回调，重新生成所有项目 DOM。通常在添加、修改数据后调用。
返回值： 无。

置请求加载项目回调(回调函数)

功能： 设置每个项目的渲染回调函数。这是宫格框最核心的方法，开发者在此回调中创建并返回一个视图组件，用于表示每个格子的内容。
参数： 回调函数，格式为 (项目集合, 索引) => { ... 返回组件 }。
- 项目集合：当前所有数据数组。
- 索引：当前正在渲染的项目索引。
返回值： 必须返回一个视图组件（继承自 视图 的实例），该组件将被添加到对应的格子中。

示例：

宫格框1.置请求加载项目回调((项目集合, 索引) => {
    变量 项 = 项目集合[索引]
    变量 标签 = 创建 标签()
    标签.文本 = 项.标题
    返回 标签
})

事件说明

宫格框本身没有定义特有的事件，但每个项目容器（在渲染回调中返回的组件）可以绑定自己的事件（如 置被单击回调）。也可通过为宫格框自身添加 置被单击回调 来捕获整体点击，但无法区分具体项目。

⚠️ 注意事项

必须调用 渲染()：在添加、删除、更新数据后，必须手动调用 渲染() 方法才能刷新显示。
渲染回调必须返回组件：置请求加载项目回调 中必须返回一个视图组件实例，否则该项目格子为空。
项目宽度：宫格框会根据容器宽度和项目数量自动计算每行列数。为保证布局美观，建议在渲染回调中为每个项目容器设置固定的宽度（如 宽度 = 90），以便宫格框正确计算排列。
拉伸内容与滚动：当 拉伸内容 = 假（默认）时，容器高度固定，内容溢出会出现滚动条；若为 真，高度由内容撑开，不滚动。
对齐方式影响布局：横向对齐方式 和 纵向对齐方式 共同决定项目在格子内的位置。如果项目容器宽度不固定，可能导致布局错乱。
性能考虑：当项目数量很大（如数百个）时，建议采用虚拟滚动或分页加载，避免一次性渲染过多 DOM。
事件绑定：如需为每个项目添加点击事件，可在渲染回调中为返回的组件绑定 置被单击回调，但注意闭包捕获索引的问题（轻语言不支持闭包捕获变量）。解决方案：在回调中使用数据集合和索引直接获取项目数据，或使用组件的 标记 属性存储索引。

轻语言网站开发SDK文档