滚动区域（scrollarea）

Y++ / YStudio 开发文档 · 一点滴

选择器： scrollarea · 设计器组件： 滚动区域 · 按名称： scrollarea#名称 或 #名称
支持库： 组件类库 → 滚动区域类（属性面板「控件类型」显示为「滚动区域」）
能力： 需授权开通；无权限时工具箱不可落点、含本组件的窗体无法保存/编译。开通后按本页写法使用。

用途

在固定大小的视口里放置较多控件（设置页、长表单、说明页等）。内容比视口高/宽时，用滚轮或滚动条浏览，超出部分自动裁剪。

从工具箱「布局 → 滚动区域」拖入。名称一般为「滚动区域1」；若仍显示成「分组框」，请重新从工具箱拖入。

硬约束

控件名来自窗口 XML「名称」；属性赋值无括号，方法调用必须带括号。
子控件「所属容器」设为该滚动区域名称；可用绝对坐标，也可在区内再放水平/垂直布局。
设计时即可裁剪溢出、显示滚动条；支持滚轮与拖动滑块浏览（选中时拖竖/横条即可滚动）。
属性面板中「垂直滚动条 / 水平滚动条」为下拉：自动 / 始终 / 隐藏；代码里用整数 0 / 1 / 2。
「底部留白」：运行时按像素加在内容底部（0=默认较大留白，便于滚过内容末端；1=几乎贴底）。设计态为方便继续往下拖控件，可能比运行时多留一点编辑空间。
勿虚构未列出的方法。

设计器

操作	说明
工具箱 → 布局 → 滚动区域	拖入视口
子控件所属容器	填滚动区域名称
滚轮	视口上垂直滚动；按住 Shift 时横向滚动
拖滚动条 / 点轨道	拖滑块或翻页
垂直/水平滚动条	下拉：自动 / 始终 / 隐藏
底部留白	整数像素；0=默认，1=几乎贴底
平滑滚动	真=滚轮/代码滚动带过渡；拖条仍瞬时

属性

属性	类型	读写	说明
`左边` / `顶边` / `宽度` / `高度`	小数	读写	视口几何
`停靠`	整数	读写	0无 1上 2下 3左 4右 5填充
`可见` / `启用`	逻辑	读写
`背景色` / `透明背景`	—	读写	视口底板
`显示边框` / `边框大小` / `边框颜色` / `圆角`	—	读写	外壳
`垂直滚动条`	整数	读写	0=自动 1=始终 2=隐藏
`水平滚动条`	整数	读写	0=自动 1=始终 2=隐藏
`底部留白`	整数	读写	内容底额外像素；0=默认（约视口高度 40%，夹在 96～240）；>0=固定像素
`平滑滚动`	逻辑	读写	真=滚轮与代码滚动平滑逼近
`水平滚动位置`	整数	读写	水平偏移（像素）
`垂直滚动位置`	整数	读写	垂直偏移（像素）
`内容宽度` / `内容高度`	整数	只读	含底部留白后的内容范围
`可视宽度` / `可视高度`	整数	只读	扣除滚动条占位后的视口
`需要水平滚动条` / `需要垂直滚动条`	整数	只读	0/1（按当前策略是否显示条）
`句柄`	长整数	只读	组件逻辑句柄

本组件没有「标题 / 显示标题」（不是分组框）。

方法

方法	说明
`取滚动位置()`	返回垂直滚动像素
`置滚动位置(位置)`	设置垂直滚动像素
`取水平滚动位置()`	返回水平滚动像素
`置水平滚动位置(位置)`	设置水平滚动像素
`滚到(水平, 垂直)`	同时设置水平与垂直位置
`滚过(水平增量, 垂直增量)`	相对当前偏移
`刷新()`	按当前子控件范围重算内容区（改完留白/策略后可调用）

事件

事件	说明
`滚动`	滚动位置变化；形参当前值 = 垂直像素（整数）。水平位置请读属性 `水平滚动位置`

函数 滚动区域1.滚动(整数 当前值) {
    输出("垂直=" + 到文本(当前值) + " 水平=" + 到文本(滚动区域1.水平滚动位置))
}

行为

操作	说明
滚轮	视口内垂直滚动；Shift+滚轮横向
拖滚动条 / 点轨道	拖动滑块或按页翻动
子控件裁剪	画出视口外的部分不显示

示例

函数 主窗口.创建完毕() {
    滚动区域1.垂直滚动条 = 0
    滚动区域1.水平滚动条 = 0
    滚动区域1.底部留白 = 1
    滚动区域1.平滑滚动 = 真
    滚动区域1.刷新()
    滚动区域1.滚到(0, 0)
}

函数 按钮到底.单击(整数 X, 整数 Y) {
    整数 h = 滚动区域1.内容高度 - 滚动区域1.可视高度
    如果 (h < 0) {
        h = 0
    }
    滚动区域1.置滚动位置(h)
}

函数 滚动区域1.滚动(整数 当前值) {
    标签状态.标题 = "垂直滚动=" + 到文本(当前值)
}

与布局配合

区内可再放「垂直布局 / 水平布局」，子控件挂到布局，布局所属容器为滚动区域。
也可全部绝对定位（适合固定设置页）。
窗口拉伸时：给滚动区域设停靠「填充」，视口随窗变大，内容仍可滚动。

详见窗口布局。

YSS

支持。 写窗体 .yss 即可改视口外壳外观（与分组框客户区同类键）。

选择器	说明
`scrollarea` / `滚动区域`	所有滚动区域
`scrollarea#滚动区域1`	按名称（推荐）
`#滚动区域1`	仅按名称
`groupbox#滚动区域1`	亦可（底座同组）

常用键：background-color、transparent-background、border-color / border-width / border-radius / show-border、box-shadow 等。
本组件无标题，不必写标题色/text。子控件样式用后代选择器（如 scrollarea#滚动区域1 label）。

不要用 YSS 改滚动位置、底部留白或子控件坐标（几何交给设计器/属性）。

scrollarea#滚动区域1 {
    background-color: #252526;
    border-color: #5A5A5A;
    border-width: 1;
    border-radius: 6;
    show-border: true;
}