skyline-components

Skyline 组件开发指南

适用场景

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

组件支持概览

完全支持的高频组件

组件	Skyline 特性增强
scroll-view	type 模式、worklet 回调、嵌套滚动、下拉二级
swiper	layout-type 堆叠/卡片、indicator 动画类型
text	overflow 文本溢出处理、max-lines
image	fade-in 渐显、默认懒加载
input/textarea	worklet 键盘回调、输入法事件
view/button	完全支持

Skyline 新增组件

组件	说明
list-view	列表布局容器
grid-view	网格/瀑布流容器
sticky-section/sticky-header	吸顶布局
nested-scroll-header/body	嵌套滚动
draggable-sheet	半屏可拖拽
share-element	共享元素动画
snapshot	截图组件
span	内联混排

文档索引

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

我想要...	查阅文档
实现长列表/虚拟列表	scroll/scroll-view.md
下拉刷新/下拉二级	scroll/scroll-view.md#下拉刷新
嵌套滚动	scroll/nested-scroll.md
列表/网格布局	scroll/list-grid-view.md
吸顶效果	scroll/sticky.md
半屏拖拽面板	scroll/draggable-sheet.md
轮播图/卡片效果	layout/swiper.md
文本处理	media/text.md
图片显示	media/image.md
输入框开发	form/input.md
共享元素动画	special/share-element.md
截图功能	special/snapshot.md

强制规则

MUST（必须遵守）

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

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

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

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

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

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

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

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

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

   <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 属性详解

type 值	说明	使用场景
list	列表模式，按需渲染直接子节点	普通长列表
custom	自定义模式，支持 list-view/grid-view/sticky	复杂布局
nested	嵌套模式，处理父子 scroll-view 联动	Tab + 列表

基础列表模式

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

下拉刷新

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

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

嵌套滚动模式

<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 滚动回调

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

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

swiper 增强特性

布局类型

<!-- 堆叠效果 -->
<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>

指示器样式

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

indicator-type	效果
normal	默认圆点
worm	蠕虫动画
expand	展开动画
jump	跳跃动画
slide	滑动动画
scale	缩放动画

text 组件

文本溢出处理

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

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

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

内联混排

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

input 组件

Skyline 特有事件

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

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

draggable-sheet 半屏组件

<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>

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 共享元素

页面间共享元素动画

源页面：

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

目标页面：

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

属性说明

属性	说明
key	页面内唯一标识，源和目标必须匹配
transform	是否启用动画
transition-on-gesture	手势返回时是否动画
rect-tween-type	动画轨迹（materialRectArc/linear）

性能优化

列表性能

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

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

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

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

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

swiper 性能

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

组件差异速查

组件	WebView	Skyline	备注
scroll-view	无 type	必须 type	Skyline 增强
text	space 属性	overflow/max-lines	不同特性
image	9种裁剪模式	5种缩放模式	裁剪模式仅 WebView
swiper	snap-to-edge	layout-type/indicator-type	不同特性
input	placeholder-class	worklet 回调	不同特性

相关技能

场景	推荐技能	说明
滚动 API	skyline-scroll-api	ScrollViewContext 接口
动画开发	skyline-worklet	Worklet 动画系统
样式开发	skyline-wxss	WXSS 支持情况
路由转场	skyline-route	页面转场动画
兼容性诊断	skyline-diagnostics	自动检查组件兼容性问题

References 目录结构

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