H5 Pages
- H5 pages based on swiper5+. (Demo)
Install
# via npm
$ npm install @cycjimmy/h5-pages --save
# or via yarn
$ yarn add @cycjimmy/h5-pages
Module format
The package is ESM only:
| File | Format | Purpose |
|---|---|---|
dist/h5-pages.esm.js |
ESM | main, module and exports entry (bundlers, import) |
dist/h5-pages.umd.js |
UMD | unminified browser build for <script> tags |
dist/h5-pages.umd.min.js |
UMD | minified browser/CDN build, browser/unpkg/jsdelivr |
dist/index.d.ts |
Types | TypeScript declarations for types and the exports types condition |
- There is no CommonJS bundle. Node.js 20.19+ / 22.12+ can
require()the ESM entry, because those versions load an ES module synchronously. - The UMD builds target ES2015, so Internet Explorer is no longer supported.
- The stylesheet is not shipped as a separate
.cssfile: the CSS Modules output is inlined into the entry chunk and injected as a<style>element while the module is evaluated, so a plain<script>tag needs nothing else. - Type declarations ship with the package, so no
@types/*package is needed. They describe Swiper structurally and never referenceswiperitself.
The toolchain needs Node.js ^22.22.2 || ^24.15.0 || >=26.0.0 (see engines in
package.json and the requirements in CONTRIBUTING.md).
Usage
h5-pages based on Swiper5+. Add script of swiper in your project first.
Methods
init(): Initialization function
import { init } from '@cycjimmy/h5-pages'
import Swiper from 'swiper'
init({
Swiper, // constructor of Swiper
pages: [page1, page2], // An array of Page instances
containerExtraHtml: `<div class="swiper-pagination"></div>`, // Extra Html under swiper-container, such as navigator, etc.
swiperOptions: { // swiper configuration(loop is not supported)
direction: 'vertical',
pagination: {
el: '.swiper-pagination',
},
},
compatibleWithSafeArea: true, // Whether it is compatible with the safe area of screen. The default is true.
})
getPageByName(name): Get a single page by name
changePageTo(name, speed): Jump to the page with the specified name
name: Page name.speed: Transition duration (in ms).
Use h5Pages to Get the Core Properties
h5Pages.root: H5 root element. Don't put pages like popups directly inbody, it is recommended to userootas parent.h5Pages.swiper: Main swiper instance for H5.
import { h5Pages } from '@cycjimmy/h5-pages'
console.log(h5Pages.root) // H5 root element
console.log(h5Pages.swiper) // swiper instance
Single Page
Build Single Page
Build directly with the default Page
import { Page } from '@cycjimmy/h5-pages'
const page = new Page({
name: 'pageName', // name for page. Default is "page" with index, such as "page0".
renderHtml: `<div class="page-wrapper">page</div>`, // Html structure under swiper-slide
pageEnter: () => console.log('enter page'), // Hook function for enter the page
pageLeave: () => console.log('leave page'), // Hook function for leave the page
})
Use Page extends (recommended)
import { Page } from '@cycjimmy/h5-pages'
const page = new class extends Page {
constructor() {
super({
name: 'page',
renderHtml: `<div class="page-wrapper">page</div>`,
pageEnter: () => console.log('enter page'),
pageLeave: () => console.log('leave page'),
})
}
// paramInit(): [Option] Add your custom parameters.
paramInit() {
// In this function super.paramInit() must be called first.
super.paramInit()
// It is recommended to place your custom parameters here.
this.oneCustomElement = this.page.querySelector(`.one-custom-element`)
}
// eventBind(): [Option] Add your custom event bindings.
eventBind() {
// In this function super.eventBind() must be called first.
super.eventBind()
// It is recommended to place custom event bindings here.
this.oneCustomElement.addEventListener('click', () => {
console.log('oneCustomElement clicked')
})
}
// extraRender(): [Option] Add your custom action When the page loaded.
extraRender() {
console.log('pageLoaded')
}
// Other custom extensions
// ...
}()
Page instance Properties
name: The name of the Page instance.root: H5 root element. Same ash5Pages.root.swiper: Main swiper instance for H5. Same ash5Pages.swiper.page: The root element of the page instance, which is theswiper-slideelement.pageIndex: The index of the page instance, the same asrealIndexfor swiper.
Popup
Use Popup extends to Build a Popup
import { Popup } from '@cycjimmy/h5-pages'
const popup = new class extends Popup {
load() {
// You must Overwrite this function with your own function
}
// Other custom extensions
// ...
}()
Popup Instance Methods
load(): Load(Show off) the popup. You must Overwrite this function with your own function. It may return nothing or aPromise<void>.render(htmlText): Render custom html texts and add the popup to the root element of h5 page.remove(): Remove the popup from the root element of h5 page.
Popup instance Properties
root: H5 root element. Same ash5Pages.root.popup: The root element of the popup instance.
CDN
To use via a CDN include this in your HTML:
<script src="https://cdn.jsdelivr.net/npm/@cycjimmy/h5-pages@5/dist/h5-pages.umd.min.js"></script>
The UMD build exposes the global h5Pages, the same named exports as the ESM
entry (Page, Popup, init, getPageByName, changePageTo, h5Pages).