Skyline Components

Skyline 组件开发指南

适用场景

• 开发滚动列表/瀑布流/网格布局
• 实现下拉刷新、下拉二级功能
• 使用嵌套滚动模式
• 开发轮播图、卡片切换效果
• 处理表单输入（input/textarea）
• 实现共享元素/页面转场动画
• 开发半屏可拖拽面板

组件支持概览

完全支持的高频组件

Skyline 新增组件

文档索引

根据需求快速定位（路径相对于 references/）：

强制规则

MUST（必须遵守）

1. scroll-view 必须指定 type：Skyline 下使用 scroll-view 必须设置 type 属性

   htmlCopy code
   <!-- ✅ 正确 -->
   <scroll-view type="list" scroll-y>...</scroll-view>
   
   <!-- ❌ 错误：缺少 type -->
   <scroll-view scroll-y>...</scroll-view>
   

2. 横向滚动需 enable-flex：横向滚动需同时开启 enable-flex 以兼容 WebView

   htmlCopy code
   <scroll-view scroll-x enable-flex style="flex-direction: row;">
   

3. 文本必须用 text 组件：内联文本只能用 <text> 组件

   htmlCopy code
   <!-- ✅ 正确 -->
   <text>Hello <text>World</text></text>
   
   <!-- ❌ 错误：内联文本不能用 view -->
   <view>Hello <view>World</view></view>
   

4. list-view/grid-view 必须在 custom 模式：

   htmlCopy code
   <scroll-view type="custom" scroll-y>
     <list-view>...</list-view>
   </scroll-view>
   

5. 嵌套滚动必须使用 nested 模式：

   htmlCopy code
   <scroll-view type="nested" scroll-y>
     <nested-scroll-header>...</nested-scroll-header>
     <nested-scroll-body>...</nested-scroll-body>
   </scroll-view>
   

NEVER（禁止行为）

1. NEVER 在 scroll-view 外直接放置 list-view/grid-view
2. NEVER 在 list-view 中使用非直接子节点列表项
3. NEVER 在 Skyline 使用 web-view/editor/movable-view 组件
4. NEVER 依赖 image 的 WebView-only 裁剪模式（top/bottom/center/left/right）

scroll-view 核心用法

type 属性详解

基础列表模式

htmlCopy code
<!-- 列表模式：直接子节点按需渲染 -->
<scroll-view 
  type="list" 
  scroll-y
  style="height: 100vh;"
  bindscrolltolower="loadMore"
>
  <view wx:for="{{list}}" wx:key="id">
    {{item.name}}
  </view>
</scroll-view>

下拉刷新

htmlCopy code
<scroll-view
  type="list"
  scroll-y
  refresher-enabled="{{true}}"
  refresher-triggered="{{refreshing}}"
  bindrefresherrefresh="onRefresh"
>
  <view slot="refresher" class="custom-refresher">
    自定义刷新区域
  </view>
  <!-- 列表内容 -->
</scroll-view>

javascriptCopy code
Page({
  data: { refreshing: false },
  onRefresh() {
    this.setData({ refreshing: true })
    // 加载数据...
    setTimeout(() => {
      this.setData({ refreshing: false })
    }, 1000)
  }
})

嵌套滚动模式

htmlCopy code
<scroll-view type="nested" scroll-y>
  <nested-scroll-header>
    <view>顶部固定区域</view>
  </nested-scroll-header>
  <nested-scroll-body>
    <swiper>
      <swiper-item wx:for="{{tabs}}" wx:key="id">
        <scroll-view 
          type="list" 
          scroll-y
          associative-container="nested-scroll-view"
        >
          <!-- 列表内容 -->
        </scroll-view>
      </swiper-item>
    </swiper>
  </nested-scroll-body>
</scroll-view>

Worklet 滚动回调

htmlCopy code
<scroll-view
  type="list"
  scroll-y
  worklet:onscrollupdate="onScrollUpdate"
>

javascriptCopy code
Page({
  onScrollUpdate(e) {
    'worklet'
    // 在 UI 线程执行，无延迟
    console.log(e.detail.scrollTop)
  }
})

swiper 增强特性

布局类型

htmlCopy code
<!-- 堆叠效果 -->
<swiper layout-type="stackLeft">
  <swiper-item>...</swiper-item>
</swiper>

<!-- 卡片滑动 -->
<swiper layout-type="tinder">
  <swiper-item>...</swiper-item>
</swiper>

<!-- 过渡动画 -->
<swiper layout-type="transformer" transformer-type="threeD">
  <swiper-item>...</swiper-item>
</swiper>

指示器样式

htmlCopy code
<swiper
  indicator-dots
  indicator-type="worm"
  indicator-color="rgba(0,0,0,0.3)"
  indicator-active-color="#000"
  indicator-margin="10"
  indicator-spacing="4"
>

text 组件

文本溢出处理

htmlCopy code
<!-- 单行省略 -->
<text overflow="ellipsis" max-lines="1">
  这是一段很长的文本内容...
</text>

<!-- 多行省略 -->
<text overflow="ellipsis" max-lines="3">
  这是一段很长的文本内容...
</text>

<!-- 渐隐效果 -->
<text overflow="fade" max-lines="1">
  这是一段很长的文本内容...
</text>

内联混排

htmlCopy code
<!-- 使用 span 实现图文混排 -->
<span>
  <image src="icon.png" style="width:20px;height:20px;" />
  <text>图文混排内容</text>
</span>

input 组件

Skyline 特有事件

htmlCopy code
<input
  value="{{value}}"
  bindinput="onInput"
  bind:selectionchange="onSelectionChange"
  bind:keyboardcompositionend="onCompositionEnd"
  worklet:onkeyboardheightchange="onKeyboardHeight"
/>

javascriptCopy code
Page({
  onKeyboardHeight(e) {
    'worklet'
    // UI 线程回调，可用于同步调整布局
    const { height, pageBottomPadding } = e.detail
  }
})

draggable-sheet 半屏组件

htmlCopy code
<draggable-sheet
  class="sheet"
  initial-child-size="0.5"
  min-child-size="0.2"
  max-child-size="0.8"
  snap="{{true}}"
  snap-sizes="{{[0.4, 0.6]}}"
  worklet:onsizeupdate="onSizeUpdate"
>
  <scroll-view
    scroll-y
    type="list"
    associative-container="draggable-sheet"
  >
    <!-- 内容 -->
  </scroll-view>
</draggable-sheet>

javascriptCopy code
Page({
  onReady() {
    this.createSelectorQuery()
      .select('.sheet')
      .node()
      .exec(res => {
        const sheetContext = res[0].node
        sheetContext.scrollTo({
          size: 0.7,
          animated: true,
          duration: 300
        })
      })
  }
})

share-element 共享元素

页面间共享元素动画

源页面：

htmlCopy code
<share-element key="hero-image" transform>
  <image src="{{item.cover}}" />
</share-element>

目标页面：

htmlCopy code
<share-element key="hero-image" transform transition-on-gesture>
  <image src="{{detail.cover}}" />
</share-element>

属性说明

性能优化

列表性能

1. 使用 list 模式：确保只渲染可见区域

   htmlCopy code
   <scroll-view type="list" scroll-y cache-extent="500">
   

2. 指定 cache-extent：预渲染视口外区域，优化滚动体验

3. 使用 list-item 属性：启用样式共享

   htmlCopy code
   <view wx:for="{{list}}" wx:key="id" list-item>
   

swiper 性能

htmlCopy code
<!-- 使用 cache-extent 预渲染相邻页 -->
<swiper cache-extent="1">

组件差异速查

相关技能

References 目录结构

Copy code
references/
├── form/
│   └── input.md
├── gesture/
│   ├── gesture-negotiation.md
│   └── gesture-system.md
├── layout/
│   └── swiper.md
├── media/
│   ├── image.md
│   └── text.md
├── scroll/
│   ├── draggable-sheet.md
│   ├── list-grid-view.md
│   ├── nested-scroll.md
│   ├── scroll-view.md
│   └── sticky.md
└── special/
    ├── share-element.md
    └── snapshot.md