A beautiful 3D gift box component with interactive animations, customizable styles, and dynamic grid layout
npm install gift-box-3dbash
npm install gift-box-3d
`
Quick Start / 快速开始
$3
#### Option 1: Direct Include / 方式1：直接引入
`html
Gift Box 3D
`
#### Option 2: CDN / 方式2：CDN
`html
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/gift-box-3d@latest/dist/test.css"
>
src="https://cdn.jsdelivr.net/npm/gift-box-3d@latest/dist/index.js"
>
`
#### Option 3: ES Modules / 方式3：ES模块
`javascript
import "gift-box-3d/dist/test.css";
window.boxconfig = {
count: "3*3",
logo: "https://example.com/logo.png",
topImage: "https://example.com/top.png",
prize: "https://example.com/prize.png",
};
// Load the script dynamically
const script = document.createElement("script");
script.src = "node_modules/gift-box-3d/dist/index.js";
document.body.appendChild(script);
`
Configuration / 配置
$3
`javascript
window.boxconfig = {
// Image Configuration / 图片配置
logo: "https://example.com/logo.png", // Logo image URL
topImage: "https://example.com/top.png", // Top decoration image URL
prize: "https://example.com/prize.png", // Prize image URL
// Color Configuration / 颜色配置
ribbonColor: "#FED01E", // Ribbon color
// Lid Colors / 盖子颜色
lidColorDark: "#d42127",
lidColorMedium: "#c91f25",
lidColorLight: "#bf1e23",
lidColorDarker: "#b41c21",
lidColorDarkest: "#aa1a1f",
// Body Colors / 盒子主体颜色
bodyColorLight: "#0666aa",
bodyColorMedium: "#0560a1",
bodyColorDark: "#055b98",
bodyColorDarker: "#05568f",
bodyColorDarkest: "#044d81",
// Callback Functions / 回调函数
emptyCallback: function (box) {
// Called when the first box is opened (empty box)
console.log("First box opened!", box);
},
secondCallback: function (box) {
// Called when the second box is opened (with prize)
console.log("Second box opened!", box);
},
// Grid Configuration / 网格配置
count: "33", // Grid layout: 'rowscolumns' (e.g., '11', '33', '2*4')
boxClassName: "custom-box", // Custom CSS class name for boxes
width: null, // Force box width in pixels (null for auto)
height: null, // Force box height in pixels (null for auto, square)
};
`
$3
The count parameter controls the grid layout:
- '1*1' - 1 box (1 row × 1 column)
- '3*3' - 9 boxes (3 rows × 3 columns)
- '2*4' - 8 boxes (2 rows × 4 columns)
count 参数控制网格布局：
- '1*1' - 1个盒子（1行 × 1列）
- '3*3' - 9个盒子（3行 × 3列）
- '2*4' - 8个盒子（2行 × 4列）
Customization / 自定义
$3
You can add custom CSS classes to boxes using the boxClassName option:
`javascript
window.boxconfig = {
boxClassName: "my-custom-box",
};
`
Then style them in your CSS:
`css
.my-custom-box {
border: 2px solid red;
box-shadow: 0 0 20px rgba(255, 0, 0, 0.5);
}
.my-custom-box .gift-box-3d {
transform: rotateX(-20deg) rotateY(20deg);
}
`
$3
`javascript
window.boxconfig = {
width: 150, // Fixed width in pixels
height: 150, // Fixed height in pixels
};
`
Events / 事件
$3
The component provides two callback functions:
组件提供两个回调函数：
1. emptyCallback - Triggered when the first box is opened (empty box)
- emptyCallback - 第一个盒子打开时触发（空盒子）
2. secondCallback - Triggered when the second box is opened (with prize)
- secondCallback - 第二个盒子打开时触发（有奖品）
`javascript
window.boxconfig = {
emptyCallback: function (box) {
alert("First box opened!");
},
secondCallback: function (box) {
alert("Second box opened with prize!");
},
};
`
Browser Support / 浏览器支持
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)
API Reference / API参考
$3
#### applyBoxConfig()
Applies CSS variable configuration to the document.
将CSS变量配置应用到文档。
#### applyImageConfig()
Applies image configuration to all boxes.
将图片配置应用到所有盒子。
#### initBoxGrid()
Initializes the box grid based on configuration.
根据配置初始化盒子网格。
#### updateBox3DFaces(box)
Updates 3D face dimensions based on box size.
根据盒子尺寸更新3D面尺寸。
Examples / 示例
$3
`javascript
window.boxconfig = {
count: "2*2",
logo: "https://example.com/logo.png",
topImage: "https://example.com/top.png",
prize: "https://example.com/prize.png",
};
`
$3
`javascript
window.boxconfig = {
count: "3*3",
ribbonColor: "#FFD700",
lidColorDark: "#FF6B6B",
lidColorMedium: "#FF8E8E",
bodyColorLight: "#4ECDC4",
bodyColorMedium: "#45B8B0",
};
`
$3
`javascript
window.boxconfig = {
count: "1*1",
width: 200,
height: 200,
boxClassName: "large-box",
};
`
File Structure / 文件结构
`
gift-box-3d/
├── dist/
│ ├── index.js # Main JavaScript file
│ ├── test.css # Stylesheet
│ ├── example.html # Usage example
│ └── index.d.ts # TypeScript definitions
├── package.json
├── README.md
└── .npmignore
`
Development / 开发
$3
`bash
npm run build
`
This will extract the JavaScript from index.html and copy test.css to the
dist directory.
这将从 index.html 中提取JavaScript代码，并将 test.css 复制到 dist 目录。
$3
`bash
npm publish
``