# @hexagrams/model-preview-component

基于 React 构建的 3D 模型预览 Web 组件，使用 Three.js 和 React Three Fiber 技术。该组件让您可以轻松地在任何网页中嵌入交互式 3D 模型查看器。

## 特性

- 🎯 **Web 组件**: 可在任何 HTML 页面中使用，框架无关
- 🎨 **可自定义主题**: 支持自定义配色方案和样式
- 📱 **响应式设计**: 自动适应容器大小
- 🖱️ **交互式控制**: 内置相机控制，支持旋转、缩放和平移
- 🎮 **多种格式**: 支持 GLB、GLTF 和其他 Three.js 兼容格式
- ⚡ **性能优化**: 使用 React Three Fiber 进行高效渲染

## 安装

```bash
npm install @hexagrams/model-preview-component
```

## 使用方法

### 方法 1: 作为 ES 模块导入

```html
<!DOCTYPE html>
<html>
<head>
    <title>3D 模型查看器</title>
</head>
<body>
    <!-- 基本用法 -->
    <model-preview-component 
        model-url="path/to/your/model.glb">
    </model-preview-component>

    <!-- 使用自定义主题 -->
    <model-preview-component 
        model-url="path/to/your/model.glb"
        theme='{"background": "#f0f0f0", "accent": "#007bff"}'>
    </model-preview-component>

    <script type="module">
        import '@hexagrams/model-preview-component';
    </script>
</body>
</html>
```

### 方法 2: 直接引入脚本

```html
<!DOCTYPE html>
<html>
<head>
    <title>3D 模型查看器</title>
</head>
<body>
    <model-preview-component 
        model-url="path/to/your/model.glb">
    </model-preview-component>

    <script type="module" src="https://unpkg.com/@hexagrams/model-preview-component/dist/model-preview-component.es.js"></script>
</body>
</html>
```

### 方法 3: 在 React/Vue/Angular 项目中使用

```javascript
// 在您的 main.js 或 index.js 中
import '@hexagrams/model-preview-component';

// 然后在模板中使用
// React JSX:
<model-preview-component model-url="./model.glb" />

// Vue 模板:
<model-preview-component model-url="./model.glb"></model-preview-component>

// Angular 模板:
<model-preview-component model-url="./model.glb"></model-preview-component>
```

## 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `model-url` | string | - | **必需**。3D 模型文件的 URL 路径（GLB、GLTF 等） |
| `theme` | string (JSON) | `{}` | 可选。定义自定义主题颜色的 JSON 字符串 |

### 主题配置

`theme` 属性接受包含以下属性的 JSON 字符串：

```json
{
  "background": "#ffffff",    // 背景颜色
  "accent": "#007bff",       // UI 元素的强调色
  "text": "#333333"          // 文本颜色
}
```

示例：
```html
<model-preview-component 
    model-url="./model.glb"
    theme='{"background": "#1a1a1a", "accent": "#00ff88", "text": "#ffffff"}'>
</model-preview-component>
```

## 样式设置

可以使用 CSS 对组件进行样式设置：

```css
model-preview-component {
    width: 100%;
    height: 400px;
    border-radius: 8px;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}
```

## 浏览器支持

- Chrome 63+
- Firefox 63+
- Safari 13+
- Edge 79+

## 开发

本地构建组件：

```bash
git clone https://gitee.com/sl798970799/model-preview-component.git
cd model-preview-component
npm install
npm run build:component
```

## 许可证

MIT 许可证 - 详见 LICENSE 文件。

## 贡献

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

## 问题反馈

如果您遇到任何问题，请在 [Gitee Issues](https://gitee.com/sl798970799/model-preview-component/issues) 上报告。
