product-display-360

v1.2.0

Published

13 days ago

360˚产品展示

Downloads

249

0High
0Medium
0Low

gleason

react vue 360˚view

Product Display 360

一个轻量级、高性能的 JavaScript 库，用于展示产品的 360 度全景视图。支持触摸和鼠标交互，提供流畅的旋转体验。

✨ 功能特点

🎯 支持 360 度产品展示
🔍 支持热点标记功能
⚙️ 支持自定义初始帧
🔄 支持正反向播放
🎨 支持透明背景
📱 支持触摸和鼠标交互
🚀 高性能渲染
📦 支持模块化和传统方式使用

📦 安装

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" />

直接下载

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

🚀 快速开始

模块化开发 (推荐)

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

// 添加热点标记
CI360LIB.addHotspot({
	frame: 58,
	x: 50,
	y: 50,
	title: '产品特点',
	description: '这是一个重要的产品特点'
});

// 初始化配置
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
});

传统方式使用

在 HTML 中创建容器：

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

添加样式：

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

初始化配置：

// 添加热点标记
CI360LIB.addHotspot({
	frame: 58,
	x: 50,
	y: 50,
	title: '产品特点',
	description: '这是一个重要的产品特点'
});

// 初始化配置
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
});

⚙️ 配置参数

| 参数 | 类型 | 必填 | 默认值 | 说明 | | ------------- | ----------- | ---- | ------ | ----------------------------------------- | | container | HTMLElement | 是 | - | 容器元素 | | framesPath | string | 是 | - | 图片帧路径 | | framesFile | string | 是 | - | 图片帧文件名格式，使用 {index} 作为占位符 | | framesCount | number | 是 | - | 总帧数 | | initFrame | number | 否 | 0 | 初始帧 | | framesReverse | boolean | 否 | false | 是否反向播放 | | alpha | boolean | 否 | false | 是否支持透明背景 |

🔧 开发指南

技术栈

TypeScript
Rollup
PostCSS
Babel

开发环境设置

克隆项目并安装依赖：

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

开发命令：

# 开发模式
npm run dev

# 构建
npm run build

# 生成类型声明文件
npm run build:types

项目结构

product-display-360/
├── src/                # 源代码目录
│   ├── core/          # 核心功能
│   ├── utils/         # 工具函数
│   └── types/         # 类型定义
├── dist/              # 构建输出目录
├── types/             # TypeScript 类型声明文件
├── rollup.config.ts   # Rollup 配置文件
├── tsconfig.json      # TypeScript 配置文件
└── package.json       # 项目配置文件

📝 最佳实践

图片优化
- 使用 WebP 格式图片以获得更好的性能
- 确保图片尺寸适中，建议宽度不超过 2000px
- 使用 CDN 加速图片加载
性能优化
- 合理设置 framesCount，建议不超过 200 帧
- 使用 requestAnimationFrame 进行动画
- 适当使用图片预加载
热点标记
- 热点数量建议控制在 10 个以内
- 确保热点位置准确，避免重叠
- 提供清晰的标题和描述

⚠️ 注意事项

确保图片帧的命名格式正确
图片帧数量需要与 framesCount 参数匹配
建议使用 CDN 加载图片资源以提高性能
支持 TypeScript 类型提示
支持 ES6+ 模块化导入

🤝 贡献指南

欢迎提交 Issue 和 Pull Request。在提交 PR 之前，请确保：

代码符合项目规范
添加了必要的测试
更新了相关文档

📄 许可证

MIT

👨‍💻 作者

Gleason