#<scroll-coordinator> XElement

<scroll-coordinator> 是一个嵌套滚动协调组件，用于实现多层可滚动容器之间的联动滚动，常见于滚动吸顶等主流 APP 页面结构中，一般搭配 <viewpager> 和 <list> 等组件一起构建嵌套滚动 + 分页切换的复合场景。

// ❌ 不支持：直接嵌套 listen
<scroll-view id="outer">
  <list id="inner" />
</scroll-view>

// ✅ 支持：使用 scroll-coordinator 协调嵌套滚动
<scroll-coordinator>
  <scroll-coordinator-header id="outer" />
  <scroll-coordinator-slot>
    <list id="inner" />
  </scroll-coordinator-slot>
</scroll-coordinator>

#使用指南

<scroll-coordinator> 的布局核心诉求是通过 CSS 控制：scroll-coordinator 的高度 == scroll-coordinator-slot 的高度 + toolbar 的高度。

#布局规范

• <scroll-coordinator>：纵向 flex 布局，display: flex; flex-direction: column;
• <scroll-coordinator-header>：脱离布局流，position: absolute;
• <scroll-coordinator-toolbar>：参与布局，display: flex;
• <scroll-coordinator-slot>：填充剩余空间，flex: 1;

.coordinator {
  width: 100%;
  height: 100%
  display: flex;
  flex-direction: column;
}

.coordinator-toolbar {
  display: flex;
  width: 100%;
}

.coordinator-header {
  position: absolute;
  width: 100%;
}

.coordinator-slot {
  width: 100%;
  flex-direction: column;
  flex: 1;
}

#纵向协同滚动

<scroll-coordinator-slot> 内须放置一个 <list> 完成纵向协同滚动

<scroll-coordinator class="coordinator">
  <scroll-coordinator-header class="coordinator-header">
    <Header />
  </scroll-coordinator-header>
  <scroll-coordinator-slot class="coordinator-slot">
    <list />
  </scroll-coordinator-slot>
</scroll-coordinator>

scroll-coordinatorsrc/base/index.tsx

Code

预览

#内部横向分页滚动

<scroll-coordinator-slot> 内部能够感知 <viewpager> 的页面切换事件，并与其中的 <list> 重新绑定嵌套滚动关系。

<scroll-coordinator class="coordinator">
  <scroll-coordinator-header class="coordinator-header">
    <Header />
  </scroll-coordinator-header>
  <scroll-coordinator-slot class="coordinator-slot">
    <Tabs />
    <viewpager>
      <viewpager-item>
        <list />
      </viewpager-item>
    </viewpager>
  </scroll-coordinator-slot>
</scroll-coordinator>

scroll-coordinatorsrc/viewpager/index.tsx

Code

预览

#整体下拉刷新

用<refresh>对<scroll-coordinator>进行包裹，并指定refresh-mode="fold" bounces={true}，构建页面级别的下拉刷新效果

<refresh>
  <refresh-header>
    <Loading />
  </refresh-header>
  <scroll-coordinator class="coordinator" bounces={true} refresh-mode="fold">
    <scroll-coordinator-header class="coordinator-header">
      <Header />
    </scroll-coordinator-header>
    <scroll-coordinator-slot class="coordinator-slot">
      <viewpager>
        <viewpager-item>
          <list />
        </viewpager-item>
      </viewpager>
    </scroll-coordinator-slot>
  </scroll-coordinator>
</refresh>

scroll-coordinatorsrc/refresh/index.tsx

Code

预览

#局部下拉刷新

用<refresh>对<scroll-coordinator-slot>内的<list>进行包裹，并指定refresh-mode="page" bounces={false}，构建局部下拉刷新效果

<scroll-coordinator class="coordinator" bounces={false} refresh-mode="page">
  <scroll-coordinator-header class="coordinator-header">
    <Header />
  </scroll-coordinator-header>
  <scroll-coordinator-slot class="coordinator-slot">
    <viewpager>
      <viewpager-item>
        <refresh>
          <refresh-header />
          <list />
        </refresh>
      </viewpager-item>
    </viewpager>
  </scroll-coordinator-slot>
</scroll-coordinator>

scroll-coordinatorsrc/refresh-inner/index.tsx

Code

预览

#属性

#android-nested-scroll-as-child

// @默认值: false
'android-nested-scroll-as-child'?: boolean;

Android foldview 基于 CoordinateLayout，但它仅实现了 NestedScrollingParent，因此不支持作为子组件嵌套在其他滚动组件中，将此属性设置为 true 可使其正常工作。

#bounces

// @默认值: true
bounces?: boolean;

当 coordinator 滚动超出边界时启用回弹效果。

#enable-scroll

// @默认值: true
'enable-scroll'?: boolean;

设置 coordinator 是否可以垂直滚动。

#enable-scroll-bar

// @默认值: false
'enable-scroll-bar'?: boolean;

设置 coordinator 滚动时滚动条是否可见。

#granularity

// @默认值: 0.01
granularity?: number;

bindoffset 的事件响应粒度，一旦滚动距离超过可滚动距离的 granularity 倍，即可能触发。默认值为 0.01，但不一定每 0.01 都会触发。

#header-over-slot

// @默认值: false
'header-over-slot'?: boolean;

此属性控制 header 层级是否高于 slot，当 header 溢出时，将显示在 slot 之上。否则，将显示在 slot 之下。建议显式设置此属性，而不是使用默认值。

#ios-force-scroll-detach

// @默认值: false
'ios-force-scroll-detach'?: boolean;

是否强制使 foldview 的 nested-vertical-scroll-behavior 在 iOS 上失效，此设置对其他平台无效。

#ios-scrolls-to-top

// @默认值: false
'ios-scrolls-to-top'?: boolean;

当用户点击状态栏时，距离状态栏最近的触摸下方的滚动视图将滚动到顶部。仅限 iOS 功能。

#refresh-mode

// @默认值: 'none'
'refresh-mode'?: 'page' | 'none' | 'fold';

foldview 的下拉刷新模式，none（无，默认值）、page（分类下拉刷新）、fold（整体下拉刷新）。

#事件

前端可以绑定相应的事件回调来监听元素的运行时行为，如下所示。

#bindoffset

bindoffset = (e: ScrollCoordinatorOffsetEvent) => {};

折叠进度回调

#方法

前端可以通过 SelectorQuery API 调用组件方法。

#setFoldExpanded

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setFoldExpanded',
      params: {
        /**
         * 偏移量，支持 px 和 rpx
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @PC
         */
        offset: string;
        /**
         * 折叠时是否需要动画
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @PC
         */
        smooth: boolean;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

#兼容性