product-display-360

English | 中文

Product Display 360

A lightweight, high-performance JavaScript library for displaying 360-degree views of products. It supports touch and mouse interactions for a smooth rotation experience.

✨ Features

• 🎯 Supports 360-degree product display
• 🔍 Supports hotspot markers
• ⚙️ Supports custom initial frame
• 🔄 Supports forward and reverse playback
• 🎨 Supports transparent background
• 📱 Supports touch and mouse interactions
• 🚀 High-performance rendering
• 📦 Supports both modular and traditional usage

📦 Installation

NPM

npm install product-display-360

CDN

<script src="https://unpkg.com/product-display-360/dist/index.js"></script>
<link rel="stylesheet" href="https://unpkg.com/product-display-360/dist/index.css" />

Direct Download

<script src="./dist/index.js"></script>
<link rel="stylesheet" href="./dist/index.css" />

🚀 Quick Start

Modular Development (Recommended)

import { CI360LIB } from 'product-display-360';

// Add a hotspot
CI360LIB.addHotspot({
	frame: 58,
	x: 50,
	y: 50,
	title: 'Product Feature',
	description: 'This is an important product feature.'
});

// Initialize configuration
CI360LIB.init({
	container: document.querySelector('.product-display-360'),
	framesPath: 'https://your-cdn.com/frames/',
	framesFile: '0-{index}.jpg',
	framesCount: 199,
	initFrame: 58,
	framesReverse: true,
	alpha: true
});

Traditional Usage

• Create a container in your HTML:

<div class="product-display-360"></div>

• Add styles:

.product-display-360 {
	width: 99vw;
	height: 98vh;
	background: #c5c3c6;
	border-radius: 20px;
	overflow: hidden;
}

• Initialize configuration:

// Add a hotspot
CI360LIB.addHotspot({
	frame: 58,
	x: 50,
	y: 50,
	title: 'Product Feature',
	description: 'This is an important product feature.'
});

// Initialize configuration
CI360LIB.init({
	container: document.querySelector('.product-display-360'),
	framesPath: 'https://your-cdn.com/frames/',
	framesFile: '0-{index}.jpg',
	framesCount: 199,
	initFrame: 58,
	framesReverse: true,
	alpha: true
});

⚙️ Configuration Parameters

Parameter	Type	Required	Default	Description
container	HTMLElement	Yes	-	The container element
framesPath	string	Yes	-	Path to the image frames
framesFile	string	Yes	-	Filename format for frames, use {index} as a placeholder
framesCount	number	Yes	-	Total number of frames
initFrame	number	No	0	Initial frame
framesReverse	boolean	No	false	Whether to play in reverse
alpha	boolean	No	false	Whether to support transparent background

🔧 Development Guide

Tech Stack

• TypeScript
• Rollup
• PostCSS
• Babel

Development Setup

• Clone the project and install dependencies:

git clone [repository-url]
cd product-display-360
npm install

• Development commands:

# Development mode
npm run dev

# Build
npm run build

# Generate type declaration files
npm run build:types

Project Structure

product-display-360/
├── src/                # Source code directory
│   ├── core/          # Core functionality
│   ├── utils/         # Utility functions
│   └── types/         # Type definitions
├── dist/              # Build output directory
├── types/             # TypeScript declaration files
├── rollup.config.ts   # Rollup configuration file
├── tsconfig.json      # TypeScript configuration file
└── package.json       # Project configuration file

📝 Best Practices

• Image Optimization

  • Use WebP format for better performance.
  • Ensure image dimensions are appropriate; a width of up to 2000px is recommended.
  • Use a CDN to speed up image loading.

• Performance Optimization

  • Set framesCount reasonably; not exceeding 200 frames is recommended.
  • Use requestAnimationFrame for animations.
  • Use image preloading appropriately.

• Hotspots

  • It is recommended to have 10 or fewer hotspots.
  • Ensure hotspot positions are accurate and avoid overlap.
  • Provide clear titles and descriptions.

⚠️ Notes

• Ensure the image frame naming format is correct.
• The number of image frames must match the framesCount parameter.
• It is recommended to use a CDN to load image resources for better performance.
• Supports TypeScript type hints.
• Supports ES6+ modular imports.

🤝 Contributing

We welcome issues and pull requests. Before submitting a PR, please ensure:

• The code follows the project's standards.
• Necessary tests have been added.
• Relevant documentation has been updated.

📄 License

MIT

👨‍💻 Author

Gleason

🔗 Related Links

• GitHub Repository
• Online Demo
• Issue Tracker