组件：返回顶部按钮

返回顶部按钮组件用于在页面滚动到一定距离后，自动显示一个悬浮按钮，点击后平滑滚动回到页面顶部。它支持自定义图标、大小、形状、颜色、位置偏移和显示阈值，并可指定滚动监听容器（默认为整个窗口）。适用于长内容页面、文档阅读、电商列表等需要快速返回顶部的场景。

典型使用场景：

长文章/文档阅读（博客、帮助文档）
商品列表/搜索结果页（无限滚动后快速返回顶部）
单页应用的长页面（仪表盘、数据报表）
移动端页面（方便拇指操作）

📌 继承自视图的成员速查

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

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

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

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

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

常用操作速查

操作	属性/方法	示例
设置按钮图标	`图标`	`返回顶部按钮1.图标 = "⬆"`
设置按钮大小	`大小`	`返回顶部按钮1.大小 = 48`
设置形状	`形状`	`返回顶部按钮1.形状 = "square"`
设置背景颜色	`背景颜色`	`返回顶部按钮1.背景颜色 = "#52c41a"`
设置水平偏移（距右）	`偏移X`	`返回顶部按钮1.偏移X = 32`
设置垂直偏移（距下）	`偏移Y`	`返回顶部按钮1.偏移Y = 32`
设置显示阈值（滚动距离）	`显示阈值`	`返回顶部按钮1.显示阈值 = 600`
指定滚动监听容器	`置滚动容器(容器元素)`	`返回顶部按钮1.置滚动容器(面板1)`
手动返回顶部	`返回顶部()`	`返回顶部按钮1.返回顶部()`
显示按钮（添加到页面）	`显示(父容器)`	`返回顶部按钮1.显示()`
销毁组件	`销毁()`	`返回顶部按钮1.销毁()`

样式美化参考

返回顶部按钮的外观可通过以下属性进行自定义：

按钮形状与大小：形状 支持 "circle"（圆形，默认）和 "square"（方形）；大小 控制宽高（像素），建议不小于 40px 以保证可点击性。
图标与颜色：图标 支持文本字符（如 "↑"、"⬆"）或 emoji；背景颜色 设置按钮底色，建议使用品牌色或高亮色。
位置与偏移：按钮固定于右下角（偏移X 和 偏移Y 控制距右和距下的距离），不可更改位置（固定为右下角）。
悬停效果：可通过继承的 置鼠标被进入回调 和 置鼠标被移出回调 动态改变背景色或缩放，增强交互反馈。
过渡动画：组件默认带有淡入淡出过渡，可通过 CSS 类自定义。

CSS 美化示例（在项目 CSS 文件中定义）：

.my-back-top {
    border-radius: 50%;
    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
    transition: transform 0.3s;
}
.my-back-top:hover {
    transform: scale(1.1);
}

在代码中应用样式类：返回顶部按钮1.添加样式类("my-back-top")

基础示例

创建一个简单的返回顶部按钮，默认右下角显示，滚动超过 400px 后出现。

变量 返回顶部按钮1 = 创建 返回顶部按钮()
返回顶部按钮1.图标 = "↑"
返回顶部按钮1.大小 = 44
返回顶部按钮1.形状 = "circle"
返回顶部按钮1.背景颜色 = "#1890ff"
返回顶部按钮1.文本颜色 = "#ffffff"
返回顶部按钮1.显示阈值 = 400
返回顶部按钮1.偏移X = 24
返回顶部按钮1.偏移Y = 24

' 添加单击回调（可在此记录事件）
返回顶部按钮1.置被单击回调((源对象) => {
    调试输出("用户点击了返回顶部按钮")
})

' 显示按钮
返回顶部按钮1.显示()

综合示例：在滚动容器内使用

本示例创建一个具有固定高度的滚动容器（垂直滚动框），让返回顶部按钮监听该容器内部的滚动事件，而非整个页面。

' ========== 创建滚动容器 ==========
变量 滚动容器 = 创建 垂直滚动框()
滚动容器.左边 = 50
滚动容器.顶边 = 30
滚动容器.宽度 = 400
滚动容器.高度 = 300
滚动容器.边框 = "1px solid #e8e8e8"
滚动容器.边框圆角 = "8px"
滚动容器.背景颜色 = "#fafafa"
滚动容器.内边距 = "8px"
添加组件(滚动容器)

' 向滚动容器添加大量内容以产生滚动
变量循环(i = 1, 50, 1)
    变量 项 = 创建 标签()
    项.文本 = "第 " + i + " 行内容"
    项.内边距 = "8px"
    项.边框底边 = "1px solid #f0f0f0"
    滚动容器.添加组件(项)
结束循环

' ========== 创建返回顶部按钮（监听该容器） ==========
变量 返回顶部按钮1 = 创建 返回顶部按钮()
返回顶部按钮1.图标 = "⬆"
返回顶部按钮1.大小 = 40
返回顶部按钮1.形状 = "circle"
返回顶部按钮1.背景颜色 = "#1890ff"
返回顶部按钮1.文本颜色 = "#ffffff"
返回顶部按钮1.显示阈值 = 200  ' 容器内滚动 200px 后显示
返回顶部按钮1.偏移X = 16
返回顶部按钮1.偏移Y = 16

' 指定滚动容器（注意：需传入原生 DOM 元素）
变量 容器元素 = 滚动容器.取原生对象()
返回顶部按钮1.置滚动容器(容器元素)

' 显示按钮（父容器可以指定为滚动容器的父级，以便按钮覆盖在容器之上）
' 这里直接添加到页面，但按钮位置是相对于视口的，会影响显示。
' 更合理的做法是将按钮添加到滚动容器的父容器，并设置合适的定位。
' 但组件本身是固定定位，所以添加到 body 即可，它会覆盖在容器上方。
返回顶部按钮1.显示()

' 添加状态提示
变量 状态标签 = 创建 标签()
状态标签.左边 = 50
状态标签.顶边 = 350
状态标签.文本 = "滚动容器内容已加载，滚动查看按钮效果"
状态标签.字体大小 = "14px"
状态标签.文本颜色 = "#999"
添加组件(状态标签)