skyline-components

SKILL.md

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（必须遵守）

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

<!-- ✅ 正确 -->
<scroll-view type="list" scroll-y>...</scroll-view>

<!-- ❌ 错误：缺少 type -->
<scroll-view scroll-y>...</scroll-view>

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

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

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

<!-- ✅ 正确 -->
<text>Hello <text>World</text></text>

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

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

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

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

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

NEVER（禁止行为）

NEVER 在 scroll-view 外直接放置 list-view/grid-view

NEVER 在 list-view 中使用非直接子节点列表项

NEVER 在 Skyline 使用 web-view/editor/movable-view 组件

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）

性能优化

列表性能

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

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

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

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