# LONGPAGE and SWIPERPAGE Modes in Luban H5: A Complete Technical Guide

> Explore LONGPAGE and SWIPERPAGE modes in Luban H5. Understand how LONGPAGE scrolls vertically and SWIPERPAGE uses horizontal Swiper slides for distinct pages. Get the full technical guide.

- Repository: [小小鲁班/luban-h5](https://github.com/ly525/luban-h5)
- Tags: deep-dive
- Published: 2026-03-06

---

**LONGPAGE renders all content as a single continuous vertical scroll, while SWIPERPAGE renders each page as a discrete horizontal slide using the Swiper library.**

In the `ly525/luban-h5` open-source H5 page builder, the rendering engine supports two distinct page modes that determine how end-users navigate through your design. Understanding the architectural differences between **LONGPAGE** and **SWIPERPAGE** is essential for optimizing user experience and performance in mobile-first H5 applications.

## What Are LONGPAGE and SWIPERPAGE Modes in Luban H5?

Luban H5 abstracts page rendering through a mode flag stored in each page’s JSON configuration. The engine uses this flag to branch between two rendering strategies:

- **LONGPAGE** – Concatenates all layers and sections into a single DOM tree with standard document flow. The browser handles scrolling natively.
- **SWIPERPAGE** – Wraps each page in a Swiper slide container (`swiper-container` > `swiper-slide`), enabling touch-based horizontal navigation, pagination bullets, and programmatic slide control.

These modes are defined as constants in [`src/constants/script.js`](https://github.com/ly525/luban-h5/blob/main/src/constants/script.js) and consumed by the central renderer in [`src/engine/renderer.js`](https://github.com/ly525/luban-h5/blob/main/src/engine/renderer.js).

## Key Differences Between LONGPAGE and SWIPERPAGE

| Feature | LONGPAGE | SWIPERPAGE |
|---------|----------|------------|
| **Navigation** | Native vertical scroll | Horizontal swipe or button navigation |
| **DOM Structure** | Single continuous container | Multiple `swiper-slide` elements inside `swiper-container` |
| **Transitions** | None (instant scroll) | Configurable Swiper effects (fade, slide, cube, etc.) |
| **Pagination** | Browser scroll bar | Swiper pagination bullets or progress bar |
| **Performance** | Lighter DOM, ideal for content-heavy pages | Slightly heavier due to Swiper initialization, better for storytelling decks |
| **Mobile UX** | Standard scroll behaviour | Touch-optimized swipe gestures |

## How to Configure Page Modes in Luban H5

Page mode is declared in the page object within your project’s JSON schema. The editor persists this value under the `mode` key.

### Defining LONGPAGE Mode

Set the `mode` property to `"LONGPAGE"` for continuous scroll layouts:

```json
{
  "id": "page_001",
  "name": "Product Details",
  "mode": "LONGPAGE",
  "layers": [
    { "type": "image", "src": "hero.jpg", "y": 0 },
    { "type": "text", "content": "Features", "y": 800 }
  ]
}

```

### Defining SWIPERPAGE Mode

Set the `mode` property to `"SWIPERPAGE"` for slide-based navigation:

```json
{
  "id": "page_002",
  "name": "Onboarding Deck",
  "mode": "SWIPERPAGE",
  "swiperConfig": {
    "effect": "slide",
    "loop": false,
    "pagination": true
  },
  "layers": [ … ]
}

```

When the engine encounters `SWIPERPAGE`, it injects the Swiper initialization code into the generated HTML.

## Rendering Implementation Details

### The PAGE_MODE Enum

The canonical definitions reside in [`src/constants/script.js`](https://github.com/ly525/luban-h5/blob/main/src/constants/script.js). This enum ensures type safety across the codebase:

```javascript
// src/constants/script.js
export const PAGE_MODE = {
  LONGPAGE: 'LONGPAGE',
  SWIPERPAGE: 'SWIPERPAGE'
}

```

### Renderer Logic

The central dispatcher in [`src/engine/renderer.js`](https://github.com/ly525/luban-h5/blob/main/src/engine/renderer.js) branches based on the `mode` property:

```javascript
// src/engine/renderer.js
import { PAGE_MODE } from '@/constants/script'

function renderPage(page) {
  if (page.mode === PAGE_MODE.LONGPAGE) {
    return renderLongPage(page)
  }
  if (page.mode === PAGE_MODE.SWIPERPAGE) {
    return renderSwiperPage(page)
  }
  throw new Error(`Unknown page mode: ${page.mode}`)
}

function renderLongPage(page) {
  // Generates a single container with standard document flow
  const container = document.createElement('div')
  container.className = 'long-page-container'
  page.layers.forEach(layer => container.appendChild(renderLayer(layer)))
  return container
}

function renderSwiperPage(page) {
  // Generates swiper-container > swiper-slide structure
  const swiperContainer = document.createElement('div')
  swiperContainer.className = 'swiper-container'
  const wrapper = document.createElement('div')
  wrapper.className = 'swiper-wrapper'
  
  page.layers.forEach(layer => {
    const slide = document.createElement('div')
    slide.className = 'swiper-slide'
    slide.appendChild(renderLayer(layer))
    wrapper.appendChild(slide)
  })
  
  swiperContainer.appendChild(wrapper)
  // Swiper initialization script injected here
  return swiperContainer
}

```

When `SWIPERPAGE` is selected, the engine also injects the Swiper initialization script into the HTML `<head>`:

```javascript
// Injected into generated HTML for SWIPERPAGE
new Swiper('.swiper-container', {
  direction: 'horizontal',
  loop: false,
  pagination: { el: '.swiper-pagination', clickable: true },
  navigation: { nextEl: '.swiper-button-next', prevEl: '.swiper-button-prev' }
})

```

## Summary

- **LONGPAGE** produces a single, vertically scrolling document ideal for long‑form content and articles.
- **SWIPERPAGE** generates a Swiper‑based slide deck with horizontal navigation, perfect for presentations and onboarding flows.
- The mode is declared in the page JSON (`"mode": "LONGPAGE"` or `"mode": "SWIPERPAGE"`) and processed by [`src/engine/renderer.js`](https://github.com/ly525/luban-h5/blob/main/src/engine/renderer.js).
- [`src/constants/script.js`](https://github.com/ly525/luban-h5/blob/main/src/constants/script.js) exports the `PAGE_MODE` enum used throughout the codebase to ensure consistency.

## Frequently Asked Questions

### Can I mix LONGPAGE and SWIPERPAGE modes in the same Luban H5 project?

Yes. The mode is set per‑page, so a single project can contain multiple pages where some use `LONGPAGE` for content‑heavy sections and others use `SWIPERPAGE` for interactive galleries. The router simply loads each page with its respective renderer.

### Which mode is better for mobile performance?

**LONGPAGE** generally yields better performance on low‑end devices because it avoids the overhead of the Swiper library and relies on native scrolling. **SWIPERPAGE** is still highly optimized, but the additional DOM wrappers and JavaScript event listeners make it slightly heavier; use it when the UX benefit of swipe navigation outweighs the marginal cost.

### How do I add transition effects to SWIPERPAGE slides?

Transition effects are configured via the `swiperConfig` object in the page JSON. Set the `effect` property to `"slide"`, `"fade"`, `"cube"`, `"coverflow"`, or `"flip"`. The renderer passes these options directly to the Swiper constructor in the generated HTML.

### Where is the page mode configuration stored?

The mode is stored in the page object within the project’s JSON schema, typically under [`src/store/modules/page.js`](https://github.com/ly525/luban-h5/blob/main/src/store/modules/page.js) or the exported project JSON. When the engine runs, [`src/engine/renderer.js`](https://github.com/ly525/luban-h5/blob/main/src/engine/renderer.js) reads `page.mode` and branches accordingly, using the constants defined in [`src/constants/script.js`](https://github.com/ly525/luban-h5/blob/main/src/constants/script.js).