轻语言网站：自定义设计列表内容

文档概述

在轻语言网页开发中，用户可以完全通过中文语法自定义任何列表类型的内容，列表内容的展示在网页开发中非常重要，如果把自定义列表内容学会了，制作出漂亮的网页内容将会变得非常容易。

本节分别讲解列表框和宫格框两种容器的自定义渲染方法。两者都遵循「数据集合 + 渲染回调」的分离式渲染模型：先用 添加项目 填充数据，再用 置请求加载项目回调 定义每项的展示视图，最后调用 渲染() 触发显示。

学习目标

阅读本文档后，你应当能够掌握以下内容：

列表框的「纯文本数据 + 单标签渲染」模式
宫格框的「对象数据 + 复合布局渲染」模式
渲染回调的参数：(数据集合, 索引)，通过 数据集合[索引] 取当前项数据
在渲染回调中 创建 组件、设置样式、注册点击事件
嵌套回调中的变量捕获（如内层 置被单击回调 引用外层 索引）
弹性布局的创建与方向设置：创建弹性布局() + 方向 = "column"
宫格框的横向对齐方式：space-between 等弹性对齐值

涉及组件

组件	名称	作用	参考文档
列表框	`列表框1`	纵向列表容器，展示纯文本项	文档`列表类组件_列表框`
宫格框	`宫格框2`	网格/宫格容器，展示图文项	文档`列表类组件_宫格框`
标签	代码中 `创建标签()`	列表项的展示视图	文档`文本类组件_标签`
弹性布局	代码中 `创建弹性布局()`	宫格项的复合根布局	文档`布局类组件_弹性布局`
图片框	代码中 `创建图片框()`	宫格项的图片展示	文档`图像类组件_图片框`

📌 列表项的展示视图并非预置组件，而是在 置请求加载项目回调 中通过 创建 动态生成的。这是轻语言列表渲染的核心模式——数据与视图分离，由回调决定每项如何展示。

涉及函数与关键字

以下为本节代码中出现的轻语言关键字与内置函数：

关键字： 变量、事件 ... 结束事件、函数 ... 结束函数、变量循环 ... 结束循环、创建、返回

列表框/宫格框通用方法：

添加项目(数据) —— 向数据集合追加一条数据（可为字符串或对象）
置请求加载项目回调(回调) —— 设置渲染回调，框架按索引逐项调用取展示视图
渲染() —— 触发按当前数据集合重新渲染

渲染回调参数：

数据集合 —— 全部数据集合（数组），通过 数据集合[索引] 取当前项
索引 —— 当前正在渲染的项索引（从 0 开始）

组件创建：

创建标签() —— 实例化标签
创建弹性布局() —— 实例化弹性布局
创建图片框() —— 实例化图片框

视图通用方法/属性：

置被单击回调(回调) —— 设置被单击回调
添加组件(组件) —— 向容器追加子组件
字体大小、内边距、文本颜色、边框、边框圆角、宽度、高度 —— 样式属性
方向 = "column" —— 弹性布局方向（column 纵向，row 横向）
横向对齐方式 = "space-between" —— 宫格框子项横向分布方式

全局函数：

弹出提示(文本) —— 浏览器弹出轻提示
调试输出(内容) —— 控制台输出

自定义列表内容

列表内容表示内容按照一条一条的排列，下方为一个自定义纯文本显示的列表演示代码。

代码示例：

事件 页面加载完毕()
    渲染纯文本列表框()
结束 事件

' 注意：已在页面设计文件.spldg中添加了“列表框1”组件。
函数 渲染纯文本列表框()
    变量循环(i = 0,10,1)
        列表框1.添加项目("纯文本项目" + i)
    结束循环
    ' 监听浏览器渲染页面时，请求加载项目内容
    ' 这里的项目内容即为列表中的每个项目内容（包含对内容的排版布局）
    ' 在这个事件中，我们可以自定义创建需要展示内容的组件，然后将内容显示到组件中
    列表框1.置请求加载项目回调((数据集合,索引) =>{
        ' 创建一个标签组件、用于显示文本内容
        变量 局_标签 = 创建 标签()
        ' 自定义设置标签的外观
        局_标签.字体大小 = "20px"
        局_标签.内边距 = "10px"
        局_标签.文本颜色 = "#009956"
        ' 监听标签被单击事件
        局_标签.置被单击回调((源对象,事件源) =>{
            弹出提示("项目" + 索引 + "被单击")
        })
        ' 这里需要注意：
        ' 这里的参数 数据集合 为上一步我们添加的项目数据
        ' 参数索引是浏览器返回给我们，告诉我们需要渲染第几个数据
        局_标签.文本 = 数据集合[索引]
        ' 将标签对象返回给浏览器，浏览器将该标签添加到列表中
        返回 局_标签
    })
    ' 渲染并显示列表
    列表框1.渲染()
结束 函数

自定义宫格内容

宫格内容类似表格、宫格方式展示，下方为一个渲染图片与文本的宫格内容展示演示代码。

代码示例：

事件 页面加载完毕()
    渲染图文宫格框()
结束 事件

' 注意：已在页面设计文件.spldg中添加了“宫格框2”组件。
函数 渲染图文宫格框()
    宫格框2.横向对齐方式 = "space-between"
    宫格框2.边框 = "1px #cc1 solid"
    宫格框2.边框圆角 = "2px"
    宫格框2.内边距 = "10px"
    变量循环(i = 0,30,1)
        变量 项目对象 = { }
        项目对象.图片 = "./static/head.jpg"
        项目对象.标题 = "项目" + i
        宫格框2.添加项目(项目对象)
    结束循环
    宫格框2.置请求加载项目回调((数据集合,索引)=>{
        变量 局_根布局 = 创建 弹性布局()
        局_根布局.方向 = "column"
        '局_根布局.边框 = "1px #cc1 solid"
        变量 局_图片框 = 创建 图片框()
        局_图片框.宽度 = "180px"
        局_图片框.高度 = "120px"
        局_图片框.边框 = "1px #ccc solid"
        局_图片框.边框圆角 = "4px"
        局_图片框.图片 = 数据集合[索引].图片
        变量 局_标题标签 = 创建 标签()
        局_标题标签.文本 = 数据集合[索引].标题
        ' 将图片、标题添加到根布局
        局_根布局.添加组件(局_图片框)
        局_根布局.添加组件(局_标题标签)
        ' 注册根布局点击事件
        局_根布局.置被单击回调(()=>{
            弹出提示("图文宫格项目：" + 索引 + "被单击")
            调试输出(数据集合[索引])
        })
        返回 局_根布局
    })
    宫格框2.渲染()
结束 函数

关键代码解读

1. 「数据 + 渲染回调」分离式渲染模型

两个示例都遵循同一模型：

' ① 填充数据
变量循环(i = 0,10,1)
    列表框1.添加项目("纯文本项目" + i)
结束循环
' ② 定义渲染回调（每渲染一项调用一次）
列表框1.置请求加载项目回调((数据集合,索引) =>{
    变量 局_标签 = 创建 标签()
    局_标签.文本 = 数据集合[索引]
    返回 局_标签
})
' ③ 触发渲染
列表框1.渲染()

要点：

添加项目 只是向数据集合追加记录，不会立即产生 DOM
必须调用 渲染() 后，框架才会遍历数据集合，按索引回调取每一项的视图
回调返回的视图由容器自动添加到 DOM，开发者无需手动 添加组件
数据可为字符串（列表框示例）或对象（宫格框示例），回调中按 数据集合[索引] 取出

2. 渲染回调的两个参数

列表框1.置请求加载项目回调((数据集合,索引) =>{
    局_标签.文本 = 数据集合[索引]
})

数据集合：全部数据的数组引用，通过 数据集合[索引] 取当前项
索引：当前正在渲染的项序号（从 0 开始）
列表框示例中 数据集合[索引] 是字符串；宫格框示例中 数据集合[索引].图片 是对象属性

3. 嵌套回调中的变量捕获

列表框1.置请求加载项目回调((数据集合,索引) =>{
    变量 局_标签 = 创建 标签()
    局_标签.置被单击回调((源对象,事件源) =>{
        弹出提示("项目" + 索引 + "被单击")
    })
    局_标签.文本 = 数据集合[索引]
    返回 局_标签
})

内层 置被单击回调 引用了外层回调的参数 索引
用户点击标签时，外层渲染回调早已返回，索引 是否保持当时的值取决于闭包捕获语义
官方示例普遍采用这种写法，说明轻语言的拉姆达对回调参数按调用时的值捕获（类似 JavaScript let 语义）
每次渲染回调调用时，索引 都是独立的值，因此每个标签点击都能取到正确序号

4. 宫格框的复合项渲染

宫格框2.置请求加载项目回调((数据集合,索引)=>{
    变量 局_根布局 = 创建 弹性布局()
    局_根布局.方向 = "column"
    变量 局_图片框 = 创建 图片框()
    ' ...设置图片框属性...
    变量 局_标题标签 = 创建 标签()
    局_标题标签.文本 = 数据集合[索引].标题
    局_根布局.添加组件(局_图片框)
    局_根布局.添加组件(局_标题标签)
    返回 局_根布局
})

宫格项的展示视图是一个复合组件：以弹性布局为根，内含图片框 + 标签
创建弹性布局() 实例化弹性布局，方向 = "column" 设为纵向排列（图片在上、标题在下）
用 添加组件 把图片框和标签挂到弹性布局下
最后 返回局_根布局，宫格框会把这个复合视图添加到对应网格中

5. 宫格框的横向对齐方式

宫格框2.横向对齐方式 = "space-between"

space-between 让子项在主轴上两端对齐、中间均分
其他常用值：flex-start（左对齐）、center（居中）、space-around（等间距环绕）
实际对应 CSS justify-content 属性

6. 列表框 vs 宫格框的对比

维度	列表框	宫格框
排列方式	纵向单列	网格/多列
数据类型	字符串或对象	通常为对象（多字段）
渲染回调返回	通常单个标签	常为复合布局（弹性布局+多子组件）
典型场景	留言列表、笔记列表	图文展示、商品九宫格
渲染模型	数据 + 回调 + `渲染()`	数据 + 回调 + `渲染()`（同源）

注意事项

数据与视图分离：添加项目 不产生 DOM，必须调用 渲染() 才会触发回调生成视图。
循环边界语义：变量循环(i = 0, 10, 1) 等效于 for(i=0; i<10; i++)，即 i 小于目标值时循环、达到目标值时退出，左闭右开区间 [0, 10)，循环执行 10 次（i=0~9）。本节示例 变量循环(i = 0,10,1) 添加 10 项数据，变量循环(i = 0,30,1) 添加 30 项数据。
渲染回调返回值：回调必须 返回 一个视图组件，容器才能将其加入 DOM。若返回 空 则该项不显示。
嵌套闭包捕获：内层 置被单击回调 引用外层 索引 时，依赖拉姆达按值捕获语义。官方示例普遍采用此写法，生成代码时可参照；若遇异常应改用参数绑定。
复合视图根布局：宫格项的展示视图若为复合结构，应以一个容器（如弹性布局）作为根，把子组件挂到根下后返回根，不要返回多个组件。
方向 属性：弹性布局 方向 = "column" 为纵向，"row" 为横向。默认值因组件而异，建议显式设置。
图片路径：示例中 "./static/head.jpg" 为相对路径，实际项目中图片需放在 static 目录下。
弹出提示 字符变体：本节代码中 弹出提示 在不同文档中可能有字符显示差异（如 弹出提示`），实际为同一函数。

学习要点总结

知识点	关键代码	适用场景
数据填充	`添加项目(数据)`	列表框、宫格框
渲染回调	`置请求加载项目回调((数据集合,索引)=>{...})`	自定义列表项
触发渲染	`渲染()`	数据变化后刷新
回调参数	`数据集合[索引]`	取当前项数据
动态创建标签	`创建标签()`	列表项展示
动态创建弹性布局	`创建弹性布局()`	复合项根布局
弹性布局方向	`方向 = "column"`	纵向排列子组件
复合视图组装	`根布局.添加组件(子组件)`	宫格图文项
嵌套回调	`置被单击回调(()=>{...引用外层索引...})`	项点击事件
横向对齐	`横向对齐方式 = "space-between"`	宫格分布
回调返回值	`返回局_标签`	提供展示视图

轻语言网站开发SDK文档