WebBuilder Component 组件 autoScroll 属性完整使用方法

一、功能简介

autoScroll 是 Wb.Component（自定义 HTML 组件）内置滚动控制属性，用于处理组件内部内容超出设定高度后的溢出展示逻辑，无需编写 CSS 样式，通过可视化配置或 JSON 参数即可控制滚动条显示、内容截断、悬浮滚动、隐藏滚动条等效果。

生效前提：组件必须配置固定 height（高度）；未设置高度时组件自适应内容大小，autoScroll 将失效。

支持 5 种参数值：

1. 不配置（默认）：内容直接溢出容器
2. false：隐藏溢出内容，无滚动
3. true：始终开启滚动，永久显示滚动条
4. auto：悬浮组件时才展示滚动条
5. hide：支持滚动，但永久隐藏滚动条

二、两种配置方式

方式 1：可视化拖拽配置（实施人员推荐）

1. 在页面 viewport 容器内，拖拽添加【Component 自定义组件】
2. 选中组件，在右侧属性面板完成基础配置：
   • 设置 height 固定高度（例如 6em、200px）
   • 按需开启 frame（边框）、padding（内边距）
   • 在 html 属性填写展示文本、自定义 HTML 代码
3. 在属性列表找到 autoScroll，下拉选择对应参数：
   • 默认 /false/true /auto/hide
4. 点击预览，分别测试短内容、超长内容两种场景，确认效果。

方式 2：JSON 源码直接配置（开发人员、批量模板复用）

直接在 Component 的 properties 内增加autoScroll参数，完整示例模板：

{
    "_icon": "component",
    "text": "demoComp",
    "cls": "Wb.Component",
    "properties": {
        "cid": "demoComp",
        "html": "测试文本内容<br>超长测试溢出内容",
        "height": "3em",
        "frame": "true",
        "padding": "true",
        "autoScroll": "auto"
    }
}

修改autoScroll后的参数值即可切换滚动模式。

三、各参数使用场景与效果说明

1. 不填写 autoScroll（默认） 容器设置高度，超出内容直接向外溢出，会挤压周边组件。

使用限制：仅用于测试 Demo，正式业务系统禁止使用。

1. autoScroll:"false" 溢出内容直接截断隐藏，无滚动条，无法滑动查看完整内容。 适用：公告摘要、提示文字、简介预览区块。
2. autoScroll:"true" 开启纵向滚动，滚动条持续显示；内容不足时部分浏览器仍保留滚动条占位。 适用：操作日志、审批详情、单据长文本备注。
3. autoScroll:"auto"（后台系统首选） 默认隐藏滚动条，鼠标悬浮至组件区域自动显示滚动条。 适用：OA 表单、客户档案、台账详情、政企管理后台页面。
4. autoScroll:"hide" 支持鼠标滚轮、触控上下滚动，但界面永久隐藏滚动条。 适用：数据大屏、可视化驾驶舱、对外展示页面；建议增加文字提示引导用户滚动。

四、推荐选型标准

五、常见问题排查方法

1. 属性配置完成没有滚动效果 ✅ 检查：是否设置固定height；没有高度，滚动逻辑不会触发。
2. 滚动条样式异常、部分浏览器展示不一致 ✅ 优先使用平台原生autoScroll，不要自定义 CSS 强行覆盖滚动条样式。
3. 页面出现双层滚动 ✅ 排查父容器（viewport/container）是否同时开启滚动，禁止多层滚动嵌套。
4. 移动端无法滑动 ✅ 完成 PC 端调试后，务必真机测试移动端；部分移动端浏览器对隐藏滚动条模式存在兼容性差异。

六、开发使用规范

1. 正式项目所有文本类 Component 组件必须显式配置 autoScroll，禁止使用默认溢出模式。
2. 同页面同类组件保持统一配置，交互效果保持一致。
3. 页面上线前执行边界测试：短文本、超长文本两种场景分别验证。
4. 大屏场景使用hide模式时，建议增加文字提示，避免用户不知道区域支持滚动。

七、快速复制标准模板

后台业务通用模板（auto）

{
    "_icon": "component",
    "text": "contentComp",
    "cls": "Wb.Component",
    "properties": {
        "cid": "contentComp",
        "html": "",
        "height": "8em",
        "frame": "true",
        "padding": "true",
        "autoScroll": "auto"
    }
}

大屏专用模板（hide）

{
    "_icon": "component",
    "text": "screenComp",
    "cls": "Wb.Component",
    "properties": {
        "cid": "screenComp",
        "html": "",
        "height": "12em",
        "frame": "false",
        "padding": "true",
        "autoScroll": "hide"
    }
}