#Skeleton Screen Usage Guide

#Applicable Scenarios

• Pages where the first screen has a lot of data and API responses have certain latency.
• Page switching shows obvious blank or flashing; want a more natural transition.
• Need placeholder display linked with Light / Dark theme.

#Requirements

• Base library version >=2.27.2
• @ray-js/cli version >=1.6.30
• Developer tool (IDE) version >=0.9.0

#Basic Workflow

#Step 1: Generate snapshot skeleton code in IDE

1. Open the skeleton preview tool in IDE.

2. Adjust parameters until satisfied then click "Copy Code".

#Parameter Description

• Element Range: identifies page node hierarchy and controls generation scope.
• Ignore Element Size: filters very small elements to avoid meaningless placeholders.
• Extract Text Elements: converts text into unified styled placeholder blocks for consistent look.
• Ignore Inline Elements: excludes inline elements with uncertain width/height to avoid misalignment.
• Snapshot Background Color: configure background placeholder colors for light / dark theme.
• Custom Navigation Bar: if page uses navigationStyle = custom, check this to adapt the nav height offset.
• Keep Native Style: use the element's own background color as placeholder (otherwise unified skeleton color).
• Overlay Opacity: adjusts depth effect after stacking color blocks.

#Step 2: Create the skeleton snapshot file

Create a pageName.snapshot.html file under the corresponding page folder and paste the copied code from Step 1.

Directory Example:

└── home
    ├── index.config.ts
    ├── index.moudle.less
    ├── index.snapshot.html  # skeleton screen file
    └── index.tsx

#Step 3: Build & Verify

Execute the normal build process. In the output directory dist check whether the corresponding page contains *.snapshot.html:

Open the MiniApp page: before business logic and real content render, the skeleton placeholder layer should appear first and then naturally transition to real content.

#Skeleton Template Example

<style data-version="v2" data-remove-type="default">
  [is="snapshot-root"] {
    pointer-events: none;
    z-index: 100000;
    position: fixed;
    top: 0;
    left: 0;
    width: 100vw;
    height: 130vh;
    background-color: var(--skeleton-bg);
  }
  [is="snapshot-root"] div {
    position: absolute;
  }
  /* Additional custom styles can be appended as needed */
</style>
<div style="top: 20px; width: 20vw; height: 20vh; background-color: #eee;">
  Skeleton Element
</div>

#Dark Theme Adaptation Example

<style>
  [theme="dark"] [is="snapshot-root"] {
    background-color: #1c1c1e; /* Placeholder background in dark mode */
  }
</style>

#Custom Navigation Bar Offset Example

<style>
  [is="snapshot-root"] div {
    transform: translateY(calc(var(--app-device-navbar-height, 44px) + var(--app-device-status-height, 20px)));
  }
</style>

#Parameter Explanation

When using manual mode, you can manually remove in page lifecycle:

usePageEvent('onLoad', () => {
  const pages = getCurrentPages();
  const currentPage = pages[pages.length - 1];
  // Ensure base library >= 2.29.0 and template sets data-remove-type="manual"
  currentPage.removeSnapshot({ animation: false }); // animation: true enables fade-out transition
});

#FAQ & Troubleshooting