框架基础类：页面

文档概述

本例程演示如何监听轻语言 web 框架中页面级的生命周期事件与浏览器事件，包括：页面加载完毕、页面解析完毕、窗口尺寸改变、页面内容滚动、页面即将被关闭、页面被关闭、页面发生错误、页面获得/失去焦点等。这些事件覆盖了网页运行过程中最重要的几个时机，是初始化逻辑、资源清理、用户离开提示、响应式布局、错误监控的基础。

学习目标

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

轻语言页面级事件的命名规则与触发时机
页面加载完毕 与 页面解析完毕 的区别与用途
窗口尺寸被改变 事件配合 取窗口宽度/取窗口高度 实现响应式
页面内容被滚动 事件的监听
页面即将被关闭 事件中通过 事件源.preventDefault() 阻止关闭
页面被关闭 与 页面即将被关闭 的先后关系
页面发生错误、页面获得焦点、页面失去焦点 的用途
在 IDE 中添加页面事件的两种方式（右键菜单 / Ctrl + E 快捷键）

涉及组件

组件	名称	作用	参考文档
绝对布局	`根布局`	页面根布局容器	文档`布局类组件_绝对布局`
标签	`标签1`	显示事件触发信息	文档`文本类组件_标签`
按钮	`按钮1`	测试交互	文档`按钮类组件_按钮`

涉及函数与关键字

关键字： 事件 ... 结束事件

页面级事件：

事件名	触发时机	是否可阻止	参考文档
`页面加载完毕`	页面所有资源（含图片等）加载完成	否	文档`页面事件_页面加载完毕`
`页面解析完毕`	DOM 解析完成（早于加载完毕）	否	文档`页面事件_页面解析完毕`
`窗口尺寸被改变`	浏览器窗口尺寸变化	否	文档`页面事件_窗口尺寸被改变`
`页面内容被滚动`	页面滚动条被滚动	否	文档`页面事件_页面内容被滚动`
`页面即将被关闭`	用户尝试离开/关闭页面（可阻止）	是	文档`页面事件_页面即将被关闭`
`页面被关闭`	页面确认被关闭后	否	文档`页面事件_页面被关闭`
`页面发生错误`	页面脚本发生错误	否	文档`页面事件_页面发生错误`
`页面获得焦点`	页面获得焦点（切回当前标签）	否	文档`页面事件_页面获得焦点`
`页面失去焦点`	页面失去焦点（切换到其他标签/窗口）	否	文档`页面事件_页面失去焦点`

事件参数：

事件源 —— 部分事件可接收事件源对象，提供 preventDefault()、returnValue 等原生 DOM API

窗口信息函数：

取窗口宽度() —— 获取浏览器视口宽度
取窗口高度() —— 获取浏览器视口高度

调试函数：

调试输出(内容) —— 控制台输出
置页面标题(文本) —— 修改浏览器标签栏标题（见贪吃蛇演示示例用法）

如何添加页面事件

在轻语言 IDE 中，添加页面事件有两种方式：

右键菜单：在 .spl 文件空白处右键 → 单击「单击事件」菜单项（实际为"添加事件"菜单）
快捷键：在 .spl 文件编辑区按下 Ctrl + E

💡 页面事件无需绑定具体组件，事件名以 页面 或 窗口 开头，直接在 .spl 顶层定义即可。

程序源码

测试页面.spldg

<页面 标题="页面标题" 宽度="500" 高度="300">
	<绝对布局 名称="根布局" >
	  <标签 名称="标签1" 左边="12" 顶边="12" 高度="40" 宽度="218" 文本="我是最棒的！" />
	  <按钮 名称="按钮1" 左边="12" 宽度="218" 顶边="70" 高度="40" 文本="点击测试" />
	</绝对布局>
</页面>

测试页面.spl

' ****************************************************************************
' 版权说明：Copyright（C） All Rights Reserved VcnStudio
' 程序版本：V1.0
' 程序作者：
' 联系信息：
' 窗口描述：默认首页。
' ****************************************************************************
' 如何添加页面事件？
' 1.在空白处右键菜单
' 2.单击“单击事件”菜单项
' 3.或直接使用 “Ctrl + E” 快捷键添加
' ****************************************************************************

事件 页面加载完毕()
    标签1.文本 = "页面加载完毕，欢迎使用 VcnStudio 网站开发插件！"
结束 事件

事件 页面解析完毕()
    标签1.文本 = "页面解析完毕"
结束 事件

事件 窗口尺寸被改变()
    标签1.文本 = "页面（浏览器）窗口尺寸被改变，宽度：" + 取窗口宽度() + "，高度：" + 取窗口高度()
结束 事件

事件 页面内容被滚动()
    标签1.文本 = "页面内容被滚动"
结束 事件

事件 页面即将被关闭(事件源)
    标签1.文本 = "页面即将被关闭"
    ' 取消关闭事件
    事件源.preventDefault()
    ' 谷歌浏览器 需要设置 returnValue
    事件源.returnValue = ""
    ' 显示给用户的提示信息（部分浏览器可能不会显示自定义信息）
    返回 "你确定要离开此页面吗？"
结束 事件

事件 页面被关闭()
    调试输出("页面被关闭")
结束 事件

事件 页面发生错误(事件源)
    调试输出("页面发生错误")
结束 事件

事件 页面获得焦点()
    调试输出("页面获得焦点")
结束 事件

事件 页面失去焦点()
    调试输出("页面失去焦点")
结束 事件

关键代码解读

1. 页面加载完毕 vs 页面解析完毕

事件 页面解析完毕()       ' DOM 解析完成即触发（不等图片等资源）
    标签1.文本 = "页面解析完毕"
结束 事件

事件 页面加载完毕()       ' 所有资源（含图片、样式等）加载完成后触发
    标签1.文本 = "页面加载完毕，欢迎使用 VcnStudio 网站开发插件！"
结束 事件

对应浏览器原生的 DOMContentLoaded（解析完毕）与 load（加载完毕）事件
页面解析完毕 触发更早，适合尽早操作 DOM
页面加载完毕 触发较晚，适合依赖完整资源的初始化（如读取图片尺寸）
两者都会触发，且 页面解析完毕 必然先于 页面加载完毕

2. 窗口尺寸被改变：响应式布局基础

事件 窗口尺寸被改变()
    标签1.文本 = "页面（浏览器）窗口尺寸被改变，宽度：" + 取窗口宽度() + "，高度：" + 取窗口高度()
结束 事件

浏览器窗口尺寸变化时触发（对应原生 resize 事件）
取窗口宽度()/取窗口高度() 取视口尺寸（数字）
实际开发中常在此事件中重新计算并调整组件位置（如 置组件水平居中、调整页面布局）

3. 页面即将被关闭：阻止用户离开

事件 页面即将被关闭(事件源)
    标签1.文本 = "页面即将被关闭"
    ' 取消关闭事件
    事件源.preventDefault()
    ' 谷歌浏览器 需要设置 returnValue
    事件源.returnValue = ""
    ' 显示给用户的提示信息（部分浏览器可能不会显示自定义信息）
    返回 "你确定要离开此页面吗？"
结束 事件

对应原生 beforeunload 事件，用户尝试关闭/刷新/跳转时触发
三步阻止关闭：
1. 事件源.preventDefault() —— 阻止默认行为
2. 事件源.returnValue = "" —— Chrome 要求设置 returnValue 才能弹出确认框
3. 返回 "提示文本" —— 部分浏览器会显示该文本作为确认提示
⚠️ 注意：现代浏览器出于安全考虑，自定义提示文本通常不会被显示，浏览器只会弹出一个通用的"是否离开"确认框

4. 页面被关闭 vs 页面即将被关闭

事件 页面即将被关闭(事件源)   ' 可阻止，用户可取消关闭
    ...
结束 事件

事件 页面被关闭()              ' 不可阻止，页面确认要关闭后触发
    调试输出("页面被关闭")
结束 事件

页面即将被关闭：用户尝试离开时触发，可阻止
页面被关闭：用户确认离开后触发，不可阻止
对应原生 beforeunload 与 unload
页面被关闭 中适合做异步不可的资源清理（如发送统计请求），但页面已无法更新 UI

5. 页面发生错误：错误监控

事件 页面发生错误(事件源)
    调试输出("页面发生错误")
结束 事件

对应原生 error 事件
适合做错误上报、日志记录
事件源 含错误详情（具体字段以框架封装为准）

6. 页面获得/失去焦点：用户活跃状态监控

事件 页面获得焦点()
    调试输出("页面获得焦点")
结束 事件

事件 页面失去焦点()
    调试输出("页面失去焦点")
结束 事件

对应原生 focus 与 blur（页面级，非组件级）
用户切换到其他标签页/窗口时触发 页面失去焦点，切回时触发 页面获得焦点
实际用途：暂停/恢复动画、停止轮询、统计用户停留时长

注意事项

事件添加方式：在 IDE 中通过右键菜单或 Ctrl + E 快捷键添加，事件名以 页面/窗口 开头的是页面级事件，无需绑定组件。
页面加载完毕 vs 页面解析完毕：前者晚于后者；依赖图片等资源的初始化放前者，尽早操作 DOM 的逻辑放后者。
页面即将被关闭 的兼容性：preventDefault() + returnValue + 返回 文本三步走，但现代浏览器大多不显示自定义提示，仅弹通用确认框。
页面被关闭 中不可更新 UI：此时页面已开始卸载，DOM 操作无效；适合做不可逆的资源清理、统计上报。
窗口尺寸被改变 频率：拖动窗口时该事件会高频触发，重计算逻辑建议加节流（如用时钟定时器延迟执行）。
事件名大小写敏感：轻语言事件名为中文，大小写不敏感，但必须与框架定义的事件名完全一致。
组件级事件与页面级事件：本节为页面级事件（无组件前缀），组件事件（如 按钮1.被单击）需带组件名前缀。

学习要点总结

知识点	关键代码	适用场景
页面加载完毕	`事件页面加载完毕()`	资源依赖的初始化
页面解析完毕	`事件页面解析完毕()`	尽早操作 DOM
窗口尺寸改变	`事件窗口尺寸被改变()` + `取窗口宽度()`	响应式布局
内容滚动	`事件页面内容被滚动()`	滚动监听
阻止关闭	`事件源.preventDefault()` + `returnValue`	用户离开提示
页面被关闭	`事件页面被关闭()`	资源清理
错误监控	`事件页面发生错误(事件源)`	错误上报
焦点切换	`页面获得焦点`/`页面失去焦点`	暂停/恢复动画
添加事件	`Ctrl + E` 快捷键 / 右键菜单	IDE 操作

轻语言网站开发SDK文档