Cuttlefish Docs
  • 简体中文

    • spz-scrollbar

    何时使用

    spz-scrollbar 为任何可滚动容器提供自定义滚动进度指示器和分步导航功能。组件向模板暴露数据（progress、step 等），可灵活渲染 UI。

    支持布局

    • container

    代码演示

    <div id="scroll-content" style="height:400px;overflow:auto;">
  <!-- 长内容 -->
</div>

<spz-scrollbar id="scrollbar" layout="container" container="scroll-content" step="5">
  <template>
    <div class="progress-bar" style="width:${data.progress}%"></div>
    <button @tap="scrollbar.prev" disabled="${!data.hasPrev}">上一步</button>
    <span>步骤 ${data.step}</span>
    <button @tap="scrollbar.next" disabled="${!data.hasNext}">下一步</button>
  </template>
</spz-scrollbar>

    属性

    属性名说明类型是否必需
    container可滚动容器元素的 IDstring是
    step滚动步数。默认：5number否
    scroll-direction滚动方向：vertical（默认）或 horizontalstring否

    模板数据

    组件向子模板提供以下数据：

    字段说明类型
    progress滚动进度百分比（0–100）number
    step当前步骤索引（0 到 step 值）number
    hasPrev是否有上一步boolean
    hasNext是否有下一步boolean

    Actions

    next

    滚动到下一步位置。

    prev

    滚动到上一步位置。

    scrollToTarget

    滚动容器使指定目标元素可见。

    参数：

    • src 或 target (string)：要滚动到的元素的 CSS 选择器

    示例：

    <button @tap="scrollbar.scrollToTarget(target='#section-3')">跳转到第 3 节</button>

    工作原理

    • 如果容器元素本身没有滚动（内容未超出），组件会退而监听 body 滚动在容器视口区域内的表现。
    • 容器尺寸变化时组件会自动重新计算（通过 ResizeObserver）。

    注意事项

    • 该组件不派发自定义事件。