Applicable Scenarios
- Develop scrolling lists/waterfall/masonry layouts
- Implement pull-to-refresh and pull-down secondary functions
- Use nested scrolling mode
- Develop carousels and card switching effects
- Handle form inputs (input/textarea)
- Implement shared element/page transition animations
- Develop half-screen draggable panels
Component Support Overview
Fully Supported High-Frequency Components
| Component | Skyline Feature Enhancements |
|---|---|
| scroll-view | type modes, worklet callbacks, nested scrolling, pull-down secondary |
| swiper | layout-type stacking/card, indicator animation types |
| text | overflow text overflow handling, max-lines |
| image | fade-in gradual appearance, default lazy loading |
| input/textarea | worklet keyboard callbacks, input method events |
| view/button | Fully Supported |
New Skyline Components
| Component | Description |
|---|---|
| list-view | List layout container |
| grid-view | Grid/waterfall container |
| sticky-section/sticky-header | Sticky layout |
| nested-scroll-header/body | Nested scrolling |
| draggable-sheet | Half-screen draggable |
| share-element | Shared element animation |
| snapshot | Screenshot component |
| span | Inline mixed layout |
Documentation Index
Quickly locate according to needs (path relative to references/):
| I want to... | Consult documentation |
|---|---|
| Implement long lists/virtual lists | scroll/scroll-view.md |
| Pull-to-refresh/pull-down secondary | scroll/scroll-view.md#下拉刷新 |
| Nested scrolling | scroll/nested-scroll.md |
| List/grid layout | scroll/list-grid-view.md |
| Sticky effect | scroll/sticky.md |
| Half-screen draggable panel | scroll/draggable-sheet.md |
| Carousel/card effects | layout/swiper.md |
| Text processing | media/text.md |
| Image display | media/image.md |
| Input field development | form/input.md |
| Shared element animation | special/share-element.md |
| Screenshot feature | special/snapshot.md |
Mandatory Rules
MUST
-
scroll-view must specify type: Under Skyline, using scroll-view must set the
typeattribute<!-- ✅ 正确 --> <scroll-view type="list" scroll-y>...</scroll-view> <!-- ❌ 错误:缺少 type --> <scroll-view scroll-y>...</scroll-view> -
Horizontal scrolling requires enable-flex: Horizontal scrolling requires simultaneously enabling
enable-flexfor WebView compatibility<scroll-view scroll-x enable-flex style="flex-direction: row;"> -
Text must use the text component: Inline text can only use the
<text>component<!-- ✅ 正确 --> <text>Hello <text>World</text></text> <!-- ❌ 错误:内联文本不能用 view --> <view>Hello <view>World</view></view> -
list-view/grid-view must be in custom mode:
<scroll-view type="custom" scroll-y> <list-view>...</list-view> </scroll-view> -
Nested scrolling must use nested mode:
<scroll-view type="nested" scroll-y> <nested-scroll-header>...</nested-scroll-header> <nested-scroll-body>...</nested-scroll-body> </scroll-view>
NEVER
- NEVER Place list-view/grid-view directly outside scroll-view
- NEVER Use non-direct child list items in list-view
- NEVER Use web-view/editor/movable-view components in Skyline
- NEVER Rely on image's WebView-only clipping modes (top/bottom/center/left/right)
scroll-view Core Usage
Detailed Explanation of the type Attribute
| type Value | Description | Use Case |
|---|---|---|
| list | List mode, renders direct child nodes on demand | Regular long list |
| custom | Custom mode, supports list-view/grid-view/sticky | Complex layout |
| nested | Nested mode, handles parent-child scroll-view linkage | Tab + list |
Basic list mode
<!-- 列表模式:直接子节点按需渲染 -->
<scroll-view
type="list"
scroll-y
style="height: 100vh;"
bindscrolltolower="loadMore"
>
<view wx:for="{{list}}" wx:key="id">
{{item.name}}
</view>
</scroll-view>
Pull-to-refresh
<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)
}
})
Nested scroll mode
<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 callback
<scroll-view
type="list"
scroll-y
worklet:onscrollupdate="onScrollUpdate"
>
Page({
onScrollUpdate(e) {
'worklet'
// 在 UI 线程执行,无延迟
console.log(e.detail.scrollTop)
}
})
swiper enhanced features
Layout type
<!-- 堆叠效果 -->
<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>
Indicator style
<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 | Effect |
|---|---|
| normal | Default dot |
| worm | Worm animation |
| expand | Expand animation |
| jump | Jump animation |
| slide | Slide animation |
| scale | Scale animation |
text component
Text overflow handling
<!-- 单行省略 -->
<text overflow="ellipsis" max-lines="1">
这是一段很长的文本内容...
</text>
<!-- 多行省略 -->
<text overflow="ellipsis" max-lines="3">
这是一段很长的文本内容...
</text>
<!-- 渐隐效果 -->
<text overflow="fade" max-lines="1">
这是一段很长的文本内容...
</text>
Inline mixed layout
<!-- 使用 span 实现图文混排 -->
<span>
<image src="icon.png" style="width:20px;height:20px;" />
<text>图文混排内容</text>
</span>
input component
Skyline-specific events
<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 half-screen component
<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 shared element
Shared element animation between pages
Source page:
<share-element key="hero-image" transform>
<image src="{{item.cover}}" />
</share-element>
Target page:
<share-element key="hero-image" transform transition-on-gesture>
<image src="{{detail.cover}}" />
</share-element>
Attribute description
| Attribute | Description |
|---|---|
| key | Unique identifier within the page; source and target must match |
| transform | Whether to enable animation |
| transition-on-gesture | Whether to animate on gesture back |
| rect-tween-type | Animation trajectory (materialRectArc/linear) |
Performance optimization
List performance
-
Use list mode: ensures only the visible area is rendered
<scroll-view type="list" scroll-y cache-extent="500"> -
Specify cache-extent: pre-renders area outside the viewport to optimize scrolling experience
-
Use list-item attributes: enable style sharing
<view wx:for="{{list}}" wx:key="id" list-item>
swiper performance
<!-- 使用 cache-extent 预渲染相邻页 -->
<swiper cache-extent="1">
Component differences quick reference
| Component | WebView | Skyline | Remarks |
|---|---|---|---|
| scroll-view | No type | Type required | Skyline enhancements |
| text | space attribute | overflow/max-lines | Differences |
| image | 9 crop modes | 5 scale modes | Crop modes are WebView only |
| swiper | snap-to-edge | layout-type/indicator-type | Differences |
| input | placeholder-class | worklet callback | Differences |
Related skills
| Scenario | Recommended skill | Description |
|---|---|---|
| Scroll API | skyline-scroll-api |
ScrollViewContext interface |
| Animation development | skyline-worklet |
Worklet animation system |
| Style development | skyline-wxss |
WXSS support status |
| Route transition | skyline-route |
Page transition animation |
| Compatibility diagnostics | skyline-diagnostics |
Automatically check component compatibility issues |
References directory structure
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