SuperAPI AI Directory

skyline-components

General & other

View repository

Updated 10-16 09:46

About this skill

Skyline Component Development Guide

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

  1. scroll-view must specify type: Under Skyline, using scroll-view must set the type attribute

    <!-- ✅ 正确 -->
    <scroll-view type="list" scroll-y>...</scroll-view>
    
    <!-- ❌ 错误:缺少 type -->
    <scroll-view scroll-y>...</scroll-view>
    
  2. Horizontal scrolling requires enable-flex: Horizontal scrolling requires simultaneously enabling enable-flex for WebView compatibility

    <scroll-view scroll-x enable-flex style="flex-direction: row;">
    
  3. 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>
    
  4. list-view/grid-view must be in custom mode:

    <scroll-view type="custom" scroll-y>
      <list-view>...</list-view>
    </scroll-view>
    
  5. 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

  1. NEVER Place list-view/grid-view directly outside scroll-view
  2. NEVER Use non-direct child list items in list-view
  3. NEVER Use web-view/editor/movable-view components in Skyline
  4. 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

  1. Use list mode: ensures only the visible area is rendered

    <scroll-view type="list" scroll-y cache-extent="500">
    
  2. Specify cache-extent: pre-renders area outside the viewport to optimize scrolling experience

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