Swiper Element (WebComponent)

您所在的位置：网站首页 › images/swiper6.png › Swiper Element (WebComponent)

Swiper Element (WebComponent)

2024-07-09 13:26| 来源: 网络整理| 查看: 265

Swiper web components are available since Swiper version 9.

Custom elements are supported in all major browsers and by almost every framework.

Installation

There are few options on how to install Swiper Element into your project:

Install & Register from NPM

We can install Swiper from NPM

$ npm install swiper

When you import Swiper custom elements from node modules, we need to manually register it. It should be done only once and it registers Swiper custom elements globally.

// import function to register Swiper custom elements import { register } from 'swiper/element/bundle'; // register Swiper custom elements register(); Swiper Custom Elements from CDN

You can also install it from CDN by directly adding it to the website with tag:

In this case, it will be automatically registered, no need to call register()

Usage

After we install Swiper Element (via node modules and calling register() or by including a script tag), there are 2 web components (custom elements) available for usage:

- main Swiper element where you define all parameters - Swiper slide element Slide 1 Slide 2 Slide 3 ... Parameters As Attributes

All Swiper parameters are available in a form of kebab-case attributes on , for example:

Slide 1 Slide 2 Slide 3 ...

All parameters that are passed as objects also can be passed as attributes in a form of [key]-[subkey]="value".

For example, such configuration:

new Swiper('.swiper', { slidesPerView: 3, grid: { rows: 3, }, mousewheel: { forceToAxis: true, }, });

should be passed in this way:

Slide 1 Slide 2 Slide 3 ... Parameters As Props

In some more complex cases when we have more complex parameters objects (like with breakpoints), we can pass all parameters as HTMLElement properties.

Here, we need to add init="false" attribute to prevent Swiper from initialization until we pass all required parameters.

Slide 1 Slide 2 Slide 3 ... // swiper element const swiperEl = document.querySelector('swiper-container'); // swiper parameters const swiperParams = { slidesPerView: 1, breakpoints: { 640: { slidesPerView: 2, }, 1024: { slidesPerView: 3, }, }, on: { init() { // ... }, }, }; // now we need to assign all parameters to Swiper element Object.assign(swiperEl, swiperParams); // and now initialize it swiperEl.initialize(); Updating Parameters

Swiper parameters can be updated by directly changing Swiper element attributes or HTMLElement properties (if it was initialized with props);

Slide 1 Slide 2 Slide 3 ... Update const swiperEl = document.querySelector('swiper-container'); const buttonEl = document.querySelector('button'); buttonEl.addEventListener('click', () => { // if it was initialized with attributes swiperEl.setAttribute('slides-per-view', '3'); // or if it was initialized with props swiperEl.slidesPerView = 3; }); Access To Swiper Instance

Initialized Swiper instance is available as swiper prop of Swiper's HTMLElement:

Slide 1 Slide 2 Slide 3 ... Slide Next const swiperEl = document.querySelector('swiper-container'); const buttonEl = document.querySelector('button'); buttonEl.addEventListener('click', () => { swiperEl.swiper.slideNext(); }); Events

All Swiper events are available as native DOM events but with lowercase names and swiper prefix (configurable via events-prefix parameter). E.g. slideChange becomes swiperslidechange.

All event handler arguments are passed as array in event.detail:

Slide 1 Slide 2 Slide 3 ... const swiperEl = document.querySelector('swiper-container'); swiperEl.addEventListener('swiperprogress', (event) => { const [swiper, progress] = event.detail; }); swiperEl.addEventListener('swiperslidechange', (event) => { console.log('slide changed'); });

It is also possible to prefix emitted events names to prevent clashing with other libs or native events using events-prefix attribute/parameter:

Slide 1 Slide 2 Slide 3 ... const swiperEl = document.querySelector('swiper-container'); swiperEl.addEventListener('swiper-progress', (event) => { const [swiper, progress] = event.detail; }); swiperEl.addEventListener('swiper-slidechange', (event) => { console.log('slide changed'); }); Pagination, Navigation, Scrollbar

If you don't pass these modules elements in parameters (e.g. scrollbar.el, pagination.el), it will render them automatically, if module parameter is specified:

Slide 1 Slide 2 Slide 3 ... Lazy

If you use lazy loading images, it requires the lazy preloader element to be added to the each slide. swiper-slide component can do this automatically by adding lazy="true" attribute:

... Virtual Slides

We have 2 options to use Virtual slides in Swiper web components.

First option is to pass slides in virtual.slides array, but it will require to use element properties to initialize Swiper element:

// swiper element const swiperEl = document.querySelector('swiper-container'); // swiper parameters const swiperParams = { virtual: { // virtual slides slides: ['Slide 1', 'Slide 2', 'Slide 3'], }, }; // assign all parameters to Swiper element Object.assign(swiperEl, swiperParams); // and now initialize it swiperEl.initialize();

Since version 9, Swiper virtual slides can work with slides originally rendered in DOM. On initialize it will remove them from DOM, cache and then re-use the ones which are required:

Slide 1 Slide 2 Slide 3 ... Thumbs

In version 9 thumbs.swiper parameter also accepts CSS Selector of the thumbs swiper. So to make both with Swiper elements we can use the following:

... ... Controller

Same as with Thumbs, Controller in version 9 also accepts CSS Selector:

... ... Injecting Styles

If you need to add styles to shadow DOM scope, you can use injectStyles or injectStylesUrls parameters, e.g.:

... import { register } from 'swiper/element/bundle'; register(); const swiperEl = document.querySelector('swiper-container'); const params = { // array with CSS styles injectStyles: [ ` :host(.red) .swiper-wrapper { background-color: red; } `, ], // array with CSS urls injectStylesUrls: ['path/to/one.css', 'path/to/two.css'], }; Object.assign(swiperEl, params); swiperEl.initialize(); Core Version & Modules

There is also Core version of Swiper element available (without additional modules).

It can be imported from node modules:

// import function to register Swiper Core custom elements import { register } from 'swiper/element'; // register Swiper custom elements register();

To add modules, we need to use modules parameter as usual to include modules scripts, and we also need to add modules styles globally and also inject modules styles to the shadow DOM

... import { register } from 'swiper/element'; import { Navigation, Pagination } from 'swiper/modules'; register(); const swiperEl = document.querySelector('swiper-container'); const params = { modules: [Navigation, Pagination], // inject modules styles to shadow DOM injectStylesUrls: [ 'path/to/navigation-element.min.css', 'path/to/pagination-element.min.css', ], }; Object.assign(swiperEl, params); swiperEl.initialize();

There are following element module styles imports available:

swiper/element/css/a11y - styles required for A11y module swiper/element/css/autoplay - styles required for Autoplay module swiper/element/css/controller - styles required for Controller module swiper/element/css/effect-cards - styles required for Cards Effect module swiper/element/css/effect-coverflow - styles required for Coverflow Effect module swiper/element/css/effect-creative - styles required for Creative Effect module swiper/element/css/effect-cube - styles required for Cube Effect module swiper/element/css/effect-fade - styles required for Fade Effect module swiper/element/css/effect-flip - styles required for Flip Effect module swiper/element/css/free-mode - styles required for Free Mode module swiper/element/css/grid - styles required for Grid module swiper/element/css/hash-navigation - styles required for Hash Navigation module swiper/element/css/history - styles required for History module swiper/element/css/keyboard - styles required for Keyboard module swiper/element/css/manipulation - styles required for Manipulation module swiper/element/css/mousewheel - styles required for Mousewheel module swiper/element/css/navigation - styles required for Navigation module swiper/element/css/pagination - styles required for Pagination module swiper/element/css/parallax - styles required for Parallax module swiper/element/css/scrollbar - styles required for Scrollbar module swiper/element/css/thumbs - styles required for Thumbs module swiper/element/css/virtual - styles required for Virtual module swiper/element/css/zoom - styles required for Zoom module Slots

By default all swiper-container children are rendered as children of .swiper-wrapper element. If you need to add elements before or after there are two slots available:

container-start - will be rendered before .swiper-wrapper container-end - will be rendered after .swiper-wrapper Rendered before wrapper Rendered after wrapper Slide 1 Slide 2 Slide 3 ... Parts

There are following CSS parts are available for styling:

container - styles for wrapper - styles for button-prev - styles for prev Navigation button button-next - styles for next Navigation button pagination - styles for prev Pagination container bullet - styles for Pagination bullet element bullet-active - styles for active Pagination bullet element scrollbar - - styles for Scrollbar container

For example:

swiper-container::part(bullet-active) { background-color: red; } Register Parameters

Since 9.1.0 there is a new global window.SwiperElementRegisterParams function to register new (or extra) params that are not part of default Swiper parameters. This may be required if you use Swiper element with some custom plugins which extend Swiper parameters.

// register swiper-container HTMLElement props to be treated as Swiper parameters window.SwiperElementRegisterParams(['foo', 'bar']); const swiperEl = document.querySelector('swiper-container'); Object.assign(swiperEl, { foo: 1, bar: 2, }); swiperEl.initialize(); Usage with React

React doesn't fully supports web components yet (as for version 18). So the usage is basically the same as in HTML:

import { useRef, useEffect } from 'react'; import { register } from 'swiper/element/bundle'; register(); export const MyComponent = () => { const swiperElRef = useRef(null); useEffect(() => { // listen for Swiper events using addEventListener swiperElRef.current.addEventListener('swiperprogress', (e) => { const [swiper, progress] = e.detail; console.log(progress); }); swiperElRef.current.addEventListener('swiperslidechange', (e) => { console.log('slide changed'); }); }, []); return ( Slide 1 Slide 2 Slide 3 ... ); }; Usage with Vue

Vue has full support for web components, including passing attributes as props and listening for custom events:

Slide 1 Slide 2 Slide 3 import { register } from 'swiper/element/bundle'; register(); export default function () { setup() { const spaceBetween = 10; const onProgress = (e) => { const [swiper, progress] = e.detail; console.log(progress) }; const onSlideChange = (e) => { console.log('slide changed') } return { spaceBetween, onProgress, onSlideChange, }; } } Usage with Svelte

Svelte has full support for web components, including passing attributes as props and listening for custom events:

import { register } from 'swiper/element/bundle'; register(); const spaceBetween = 10; const onProgress = (e) => { const [swiper, progress] = e.detail; console.log(progress) }; const onSlideChange = (e) => { console.log('slide changed') } Slide 1 Slide 2 Slide 3 Usage with Solid

Solid has full support for web components, including passing attributes as props and listening for custom events:

import { register } from 'swiper/element/bundle'; register(); export default () => { const spaceBetween = 10; const onProgress = (e) => { const [swiper, progress] = e.detail; console.log(progress); }; const onSlideChange = (e) => { console.log('slide changed'); }; return ( Slide 1 Slide 2 Slide 3 ); }; What next?

As you see it is really easy to integrate Swiper into your website or app. So here are your next steps:

Go to API Documentation to learn more about all Swiper API and how to control it. Look at available Demos. If you have questions about Swiper ask them in StackOverflow or Swiper Discussions. Create issue on GitHub if you found a bug. If you are looking for support, we have a private Discord support chat room for Swiper Patrons. Edit this page on GitHub

【本文地址】

公司简介

联系我们