轻语言（Qing）XML 界面定义规范

文档概述

轻语言（Qing）框架支持两种 UI 创建方式：

纯代码方式：在 .spl 文件中使用 创建 [类名]() 动态创建界面
XML 定义方式：在 .spldg 文件中用 XML 描述界面结构，在 .spl 中通过组件名称引用

XML 定义方式适合界面结构固定、可视化设计的场景，让 UI 与逻辑分离。

学习目标

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

.spldg XML 文件的基本结构（<页面> 根节点 + 布局容器）
PC 端页面与移动端页面（类型="wap"）的差异
通用组件 XML 写法：<组件标签名称="组件名" 属性="值" />
组件的 名称 属性在 .spl 代码中的引用方式
XML 属性与代码属性/方法的对应关系
宽高/坐标必须用纯数字、字体大小等需带 px 单位的规则
.spldg 与 .spl 必须成对存在且文件名相同

XML 文件基本结构

根节点：`<页面>`

每个 .spldg 文件必须以 <页面> 为根节点，定义页面级属性。

PC电脑网站页面：

<页面 标题="页面标题" 宽度="500" 高度="300">
    <!-- 页面内容 -->
</页面>

手机移动端页面：

<页面 标题="页面标题" 宽度="500" 高度="300" 类型="wap">
    <!-- 页面内容 -->
</页面>

PC电脑网站页面不需要指定类型，手机移动端页面必须设置页面类型属性，属性值必须为：wap

页面属性说明：

属性	类型	说明
标题	文本型	页面标题，显示在浏览器标签栏
宽度	数值型	页面宽度（像素）
高度	数值型	页面高度（像素）
类型	文本型	页面类型、默认省略该属性则表示页面类型为PC电脑端网页，如果设置该属性并设置其值为“wap”则表示该页面为手机移动端类型。

布局容器：`<绝对布局>` / `<弹性布局>`

页面内的第一层必须是布局容器，用于组织子组件，除非特别说明，默认根布局只能为：绝对布局。

<页面 标题="首页" 宽度="500" 高度="300">
    <绝对布局 名称="根布局" 宽度="100%" 高度="100%">
        <!-- 子组件 -->
    </绝对布局>
</页面>

布局属性说明：

属性	说明
名称	组件名称，在 `.spl` 代码中通过此名称引用（必须唯一）
左边 / 顶边	位置（绝对布局中有效）
宽度 / 高度	尺寸，属性值只能为纯数字
背景颜色	设置布局的背景颜色

注意：所有布局、尺寸类属性（左边、顶边、宽度、高度）都必须用纯数字，不能出现 "自适应"、"auto"、"wrap_content" 这类文本值。

组件 XML 写法

通用规则

所有组件在 XML 中的写法为：

<组件标签 名称="组件名" 属性1="值1" 属性2="值2" />

组件标签：对应组件类名（如 按钮、标签、编辑框）
名称属性：必须，用于在 .spl 代码中引用该组件
其他属性：对应组件的属性名，值使用字符串或数值

常用组件示例

1. 标签（Label）

<标签 名称="标题标签" 左边="20" 顶边="20" 宽度="200" 高度="40" 
      文本="欢迎使用" 字体大小="24" 文本颜色="#333" />

2. 按钮（Button）

<按钮 名称="登录按钮" 左边="20" 顶边="100" 宽度="120" 高度="40" 
      文本="登录" 背景颜色="#1890ff" 文本颜色="#ffffff" />

3. 编辑框（TextBox）

<编辑框 名称="用户名框" 左边="20" 顶边="60" 宽度="200" 高度="32" 
         提示文本="请输入用户名" />

4. 密码框

<编辑框 名称="密码框" 左边="20" 顶边="100" 宽度="200" 高度="32" 
         提示文本="请输入密码" 类型="password" />

5. 图片框（ImageBox）

<图片框 名称="头像" 左边="20" 顶边="20" 宽度="60" 高度="60" 
         图片="static/avatar.jpg" 图片显示模式="cover" />

6. 弹性布局（FlexLayout）

<弹性布局 名称="主容器" 宽度="100%" 高度="100%" 
          方向="column" 主轴对齐="center" 侧轴对齐="center">
    <!-- 子组件 -->
</弹性布局>

在 `.spl` 代码中引用 XML 定义的组件

在 XML 中定义了 名称 属性的组件，可以在 .spl 代码中直接通过名称访问其属性和方法。

示例：完整的登录界面

界面文件：`登录页面.spldg`

<?xml version="1.0" encoding="utf-8"?>
<页面 标题="用户登录" 宽度="667" 高度="424" 背景颜色="#f5f5f5">
  <绝对布局 名称="根布局">
    <弹性布局 名称="弹性布局_登录框" 左边="80" 顶边="42" 高度="265" 宽度="500" 方向="column" 子项间距="20px" 侧轴对齐="center">
      <标签 名称="标签_1" 文本="登录账号" 字体粗细="bold" 字体大小="30px" />
      <表单输入框 名称="表单输入框_用户名" 标题="用户名" 提示文本="请输入用户名" />
      <表单输入框 名称="表单输入框_密码" 标题="密码" 提示文本="请输入密码" 输入类型="password" />
      <按钮 名称="按钮_登录" 文本="登录" 背景颜色="#1890ff" 文本颜色="#ffffff" 边框圆角="4" 高度="40" 宽度="120" />
      <标签 名称="标签_小字备注" 文本="登录小字备注信息" 文本颜色="#5E5B59" />
    </弹性布局>
  </绝对布局>
</页面>

逻辑文件：`登录页面.spl`

'* ******************************************************************************
'* 版权说明：Copyright（C） All Rights Reserved VcnStudio
'* 程序版本：V1.0
'* 文件描述：登录页面逻辑
'* 修改日志：
'* ******************************************************************************

' 页面变量，整个页面都能使用
变量 页面变量 = "用户登录页面"

' ========== 页面加载事件 ==========
事件 页面加载完毕()
    ' 页面加载后，可以做一些初始化操作
    调试输出("登录页面已加载")
    ' 例如：设置表单宽度占满登录框布局
    置组件宽度("100%",表单输入框_用户名,表单输入框_密码,按钮_登录)
    ' 将整个登录框水平垂直居中到页面中间
    置组件居中(弹性布局_登录框)
    ' 使用原生css样式值设置“小字备注”标签靠左显示
    标签_小字备注.置内联样式("align-self","flex-start")
    ' 如果想让登录框靠上一点，可以取出登录框的实际高度减去一些值
    弹性布局_登录框.顶边 = 弹性布局_登录框.取渲染顶边() - 100
结束 事件

' ========== 登录按钮点击事件 ==========
事件 按钮_登录.被单击(源对象,事件源)
    变量 用户名 = 表单输入框_用户名.内容
    变量 密码 = 表单输入框_密码.内容
    如果(用户名 == "" 或 密码 == "")
        弹出提示("用户名或密码不能为空！")
        返回
    结束 如果
    ' 发送登录请求
    变量 待提交数据 = "username=" + 用户名 + "&password=" + 密码
    请求接口("Api1", "登录账号", (结果,标记) => {
        变量 响应 = JSON解析(结果)
        如果(响应.code == 0)
            保存配置("token", 响应.token)
            切换页面("首页")
        否则
            弹出提示("登录失败：" + 响应.msg)
        结束 如果
    },待提交数据)
结束 事件

XML 属性与代码属性的对应关系

XML 属性	代码中对应的属性/方法	示例
`名称`	组件实例名称	`用户名框.内容`
`左边` / `顶边`	`.左边` / `.顶边`	`登录按钮.左边 = 20`
`宽度` / `高度`	`.宽度` / `.高度`	`标签1.宽度 = 200`
`文本`	`.文本`	`标签1.文本 = "新内容"`
`背景颜色`	`.背景颜色`	`按钮1.背景颜色 = "#1890ff"`
`文本颜色`	`.文本颜色`	`标签1.文本颜色 = "#333"`
`字体大小`	`.字体大小`	`标签1.字体大小 = "16px"`
`提示文本`	`.提示文本`	`编辑框1.提示文本 = "请输入"`
`类型`	`.类型`	`编辑框1.类型 = "password"`
`可视`	`.可视`	`标签1.可视 = 假`
`禁用`	`.禁用`	`按钮1.禁用 = 真`
`边框圆角`	`.边框圆角`	`按钮1.边框圆角 = "4px"`
`内容水平对齐方式`	`.内容水平对齐方式`	`标签1.内容水平对齐方式 = "center"`

注意事项

.spldg 与 .spl 必须成对：界面文件和逻辑文件的名称必须相同且必须同时存在。例如：登录页面.spl、登录页面.spldg 必须同时存在；其中 .spldg 是 spl design 的缩写，意为"逻辑文件的界面设计文件"。
尺寸与坐标用纯数字：宽度、高度、左边、顶边、右边、底边等赋值时使用整数值（不带单位）。
字体大小等需带 px 单位：圆角、字体大小等都必须带默认单位 px，例如：按钮1.字体大小 = "30px"。
名称 属性必须唯一：每个组件在 XML 中的 名称 属性必须唯一，用于在 .spl 中引用。
PC 与移动端差异：PC 端页面无需 类型 属性；移动端页面必须设置 类型="wap"。
根布局只能为绝对布局：除非特别说明，默认页面根布局只能为 绝对布局。

AI使用指南

当用户询问关于界面布局的问题时，你需要：

判断用户使用的是纯代码方式还是 XML 定义方式
如果用户想用 XML 定义界面：
- 提供 .spldg 文件的结构和组件 XML 写法
- 组件名称必须唯一，用于在 .spl 中引用
- 事件绑定在 .spl 中使用 事件组件名.事件名
如果用户想用纯代码方式：
- 使用 创建类名() 创建实例
- 设置属性、添加事件、添加到布局

轻语言网站开发SDK文档