gift-box-3d

v1.0.2

Published

a day ago

A beautiful 3D gift box component with interactive animations, customizable styles, and dynamic grid layout

0High
0Medium
0Low

weijunliang

gift-box 3d animation interactive css3 transform gift box prize lottery

Gift Box 3D

A beautiful, interactive 3D gift box component with customizable styles, dynamic grid layout, and smooth animations.

Features / 功能特点

🎁 3D Gift Box - Beautiful 3D gift box with realistic animations
🎨 Customizable - Fully customizable colors, images, and styles
📱 Responsive - Adaptive grid layout that works on all screen sizes
🖱️ Interactive - Mouse/touch rotation following cursor movement
🎯 Dynamic Grid - Configurable grid layout (e.g., 1x1, 3x3, etc.)
🎪 Animations - Smooth opening animations with prize reveal
🎨 CSS Variables - Easy theming with CSS custom properties

🎁 3D礼品盒 - 精美的3D礼品盒，带有逼真的动画效果
🎨 可定制 - 完全可定制的颜色、图片和样式
📱 响应式 - 自适应网格布局，适用于所有屏幕尺寸
🖱️ 交互式 - 鼠标/触摸旋转，跟随光标移动
🎯 动态网格 - 可配置的网格布局（例如：1x1、3x3等）
🎪 动画 - 流畅的打开动画，带有奖品展示
🎨 CSS变量 - 使用CSS自定义属性轻松主题化

Installation / 安装

npm install gift-box-3d

Quick Start / 快速开始

Basic Usage / 基本用法

Option 1: Direct Include / 方式1：直接引入

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Gift Box 3D</title>
        <link rel="stylesheet" href="node_modules/gift-box-3d/dist/test.css">
    </head>
    <body>
        <div data-v-45ea29a2="" class="grid-3d-boxes"></div>

        <script>
            // Configure before loading the script
            // 在加载脚本之前配置
            window.boxconfig = {
                count: "3*3", // 3 rows x 3 columns = 9 boxes
                logo: "https://example.com/logo.png",
                topImage: "https://example.com/top.png",
                prize: "https://example.com/prize.png",
            };
        </script>
        <script src="node_modules/gift-box-3d/dist/index.js"></script>
    </body>
</html>

Option 2: CDN / 方式2：CDN

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/gift-box-3d@latest/dist/test.css"
>
<script>
    window.boxconfig = {
        count: "3*3",
        logo: "https://example.com/logo.png",
        topImage: "https://example.com/top.png",
        prize: "https://example.com/prize.png",
    };
</script>
<script
    src="https://cdn.jsdelivr.net/npm/gift-box-3d@latest/dist/index.js"
></script>

Option 3: ES Modules / 方式3：ES模块

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 / 配置

Configuration Options / 配置选项

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: "3*3", // Grid layout: 'rows*columns' (e.g., '1*1', '3*3', '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)
};

Grid Layout / 网格布局

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 / 自定义

Custom CSS Classes / 自定义CSS类

You can add custom CSS classes to boxes using the boxClassName option:

window.boxconfig = {
    boxClassName: "my-custom-box",
};

Then style them in your 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);
}

Fixed Box Size / 固定盒子尺寸

window.boxconfig = {
    width: 150, // Fixed width in pixels
    height: 150, // Fixed height in pixels
};

Events / 事件

Box Opening Events / 盒子打开事件

The component provides two callback functions:

组件提供两个回调函数：

emptyCallback - Triggered when the first box is opened (empty box)
- emptyCallback - 第一个盒子打开时触发（空盒子）
secondCallback - Triggered when the second box is opened (with prize)
- secondCallback - 第二个盒子打开时触发（有奖品）

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参考

Methods / 方法

`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 / 示例

Example 1: Basic Setup / 示例1：基本设置

window.boxconfig = {
    count: "2*2",
    logo: "https://example.com/logo.png",
    topImage: "https://example.com/top.png",
    prize: "https://example.com/prize.png",
};

Example 2: Custom Colors / 示例2：自定义颜色

window.boxconfig = {
    count: "3*3",
    ribbonColor: "#FFD700",
    lidColorDark: "#FF6B6B",
    lidColorMedium: "#FF8E8E",
    bodyColorLight: "#4ECDC4",
    bodyColorMedium: "#45B8B0",
};

Example 3: Fixed Size Boxes / 示例3：固定尺寸盒子

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 / 开发

Build / 构建

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 目录。

Publish / 发布

npm publish

License / 许可证

MIT License

Contributing / 贡献

Contributions are welcome! Please feel free to submit a Pull Request.

欢迎贡献！请随时提交Pull Request。

Changelog / 更新日志

v1.0.0

Initial release
3D gift box component
Interactive mouse/touch rotation
Dynamic grid layout
Customizable colors and images
Box opening animations

v1.0.0

初始版本
3D礼品盒组件
交互式鼠标/触摸旋转
动态网格布局
可定制的颜色和图片
盒子打开动画

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Gift Box 3D

Features / 功能特点

Installation / 安装

Quick Start / 快速开始

Basic Usage / 基本用法

Option 1: Direct Include / 方式1：直接引入

Option 2: CDN / 方式2：CDN

Option 3: ES Modules / 方式3：ES模块

Configuration / 配置

Configuration Options / 配置选项

Grid Layout / 网格布局

Customization / 自定义

Custom CSS Classes / 自定义CSS类

Fixed Box Size / 固定盒子尺寸

Events / 事件

Box Opening Events / 盒子打开事件

Browser Support / 浏览器支持

API Reference / API参考

Methods / 方法

applyBoxConfig()

applyImageConfig()

initBoxGrid()

updateBox3DFaces(box)

Examples / 示例

Example 1: Basic Setup / 示例1：基本设置

Example 2: Custom Colors / 示例2：自定义颜色

Example 3: Fixed Size Boxes / 示例3：固定尺寸盒子

File Structure / 文件结构

Development / 开发

Build / 构建

Publish / 发布

License / 许可证

Contributing / 贡献

Changelog / 更新日志

v1.0.0

v1.0.0

`applyBoxConfig()`

`applyImageConfig()`

`initBoxGrid()`

`updateBox3DFaces(box)`