diff --git a/API_USAGE_EXAMPLE.md b/API_USAGE_EXAMPLE.md
new file mode 100644
index 0000000..4796721
--- /dev/null
+++ b/API_USAGE_EXAMPLE.md
@@ -0,0 +1,216 @@
+# 模型管理 API 使用示例
+
+## API 说明
+
+### 1. 添加模型
+
+```javascript
+// 添加带有 rotation 控制类型的模型
+kernel.model.add({
+ modelId: "卷帘大",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/卷帘大.glb",
+ modelControlType: "rotation"
+});
+
+// 添加带有 color 控制类型的模型
+kernel.model.add({
+ modelId: "小桌",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/小桌.glb",
+ modelControlType: "color"
+});
+
+// 添加不带控制类型的模型
+kernel.model.add({
+ modelId: "框架",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/框架.glb"
+});
+```
+
+### 2. 替换模型
+
+```javascript
+// 替换模型并指定控制类型
+kernel.model.replace({
+ modelId: "卷帘大",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/新卷帘.glb",
+ modelControlType: "rotation"
+});
+```
+
+### 3. 模型变换 (Transform)
+
+```javascript
+// 设置模型旋转 - 直接使用角度（默认）
+kernel.transform.rotation({
+ modelId: "卷帘大",
+ vector3: { x: 0, y: 90, z: 0 } // 绕Y轴旋转90度
+});
+
+// 更多角度示例
+kernel.transform.rotation({
+ modelId: "卷帘大",
+ vector3: { x: 0, y: 180, z: 0 } // 旋转180度
+});
+
+kernel.transform.rotation({
+ modelId: "卷帘大",
+ vector3: { x: 45, y: 90, z: 0 } // X轴45度，Y轴90度
+});
+
+// 如果需要使用弧度，设置 useDegrees: false
+kernel.transform.rotation({
+ modelId: "卷帘大",
+ vector3: { x: 0, y: Math.PI / 2, z: 0 },
+ useDegrees: false
+});
+
+// 设置模型位置
+kernel.transform.position({
+ modelId: "小桌",
+ vector3: { x: 10, y: 0, z: 5 }
+});
+
+// 设置模型缩放
+kernel.transform.scale({
+ modelId: "框架",
+ vector3: { x: 1.5, y: 1.5, z: 1.5 } // 放大1.5倍
+});
+```
+
+### 4. 点击事件回调
+
+```javascript
+kernel.on('model:click', (data) => {
+ console.log('点击的网格名称:', data.meshName);
+ console.log('点击的网格对象:', data.pickedMesh);
+ console.log('点击的3D坐标:', data.pickedPoint);
+ console.log('材质名称:', data.materialName);
+ console.log('模型控制类型:', data.modelControlType); // 'rotation' | 'color' | undefined
+
+ // 根据控制类型执行不同操作
+ if (data.modelControlType === 'rotation') {
+ console.log('这是一个可旋转的模型');
+ // 执行旋转相关操作 - 直接使用角度
+ kernel.transform.rotation({
+ modelId: "卷帘大",
+ vector3: { x: 0, y: 180, z: 0 }
+ });
+ } else if (data.modelControlType === 'color') {
+ console.log('这是一个可改变颜色的模型');
+ // 执行颜色相关操作
+ kernel.material.color(data.materialName, '#FF0000');
+ }
+});
+```
+
+## ModelControlType 说明
+
+- `rotation`: 表示该模型支持旋转控制
+- `color`: 表示该模型支持颜色控制
+- `undefined`: 未指定控制类型
+
+## 完整示例
+
+```javascript
+import { kernel } from './index.js';
+
+const config = {
+ container: document.querySelector('#renderDom'),
+ modelUrlList: [],
+ env: {
+ envPath: 'https://sdk.zguiy.com/resurces/hdr/hdr.env',
+ intensity: 1.2,
+ rotationY: 0.3,
+ background: true
+ },
+};
+
+kernel.init(config);
+
+// 添加多个模型
+kernel.model.add({
+ modelId: "框架",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/框架.glb"
+});
+
+kernel.model.add({
+ modelId: "卷帘大",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/卷帘大.glb",
+ modelControlType: "rotation"
+});
+
+kernel.model.add({
+ modelId: "小桌",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/小桌.glb",
+ modelControlType: "color"
+});
+
+// 模型加载完成后设置变换
+kernel.on('model:loaded', () => {
+ // 设置初始位置
+ kernel.transform.position({
+ modelId: "小桌",
+ vector3: { x: 5, y: 0, z: 0 }
+ });
+
+ // 设置初始旋转 - 直接使用角度
+ kernel.transform.rotation({
+ modelId: "卷帘大",
+ vector3: { x: 0, y: 45, z: 0 }
+ });
+
+ // 设置缩放
+ kernel.transform.scale({
+ modelId: "框架",
+ vector3: { x: 1.2, y: 1.2, z: 1.2 }
+ });
+});
+
+// 监听点击事件
+kernel.on('model:click', (data) => {
+ console.log('模型点击数据:', data);
+
+ if (data.modelControlType === 'rotation') {
+ // 处理旋转逻辑 - 每次点击旋转45度
+ kernel.transform.rotation({
+ modelId: data.meshName,
+ vector3: { x: 0, y: 45, z: 0 }
+ });
+ } else if (data.modelControlType === 'color') {
+ // 处理颜色变更逻辑
+ kernel.material.color(data.materialName, '#FF0000');
+ }
+});
+```
+
+## Transform API 详细说明
+
+### rotation - 旋转
+- 参数：`{ modelId: string, vector3: { x, y, z }, useDegrees?: boolean }`
+- **默认使用角度**：直接传递 90、180 等角度值
+- 如需使用弧度，设置 `useDegrees: false`
+- 示例：
+ ```javascript
+ // 使用角度（默认，推荐）
+ kernel.transform.rotation({
+ modelId: "model1",
+ vector3: { x: 0, y: 90, z: 0 }
+ });
+
+ // 使用弧度
+ kernel.transform.rotation({
+ modelId: "model1",
+ vector3: { x: 0, y: Math.PI / 2, z: 0 },
+ useDegrees: false
+ });
+ ```
+
+### position - 位置
+- 参数：`{ modelId: string, vector3: { x, y, z } }`
+- 单位：场景单位
+- 坐标系：右手坐标系（X右，Y上，Z前）
+
+### scale - 缩放
+- 参数：`{ modelId: string, vector3: { x, y, z } }`
+- 单位：倍数（1.0 = 原始大小）
+- 可以设置不同轴向的缩放比例
diff --git a/examples/module-demo.js b/examples/module-demo.js
index 835eeb2..d5a9f63 100644
--- a/examples/module-demo.js
+++ b/examples/module-demo.js
@@ -15,10 +15,25 @@ const config = {
};
kernel.init(config);
-kernel.model.add("卷帘大", "https://sdk.zguiy.com/resurces/model/框架.glb")
-kernel.model.add("卷帘大", "https://sdk.zguiy.com/resurces/model/卷帘大.glb")
-kernel.model.add("卷帘小", "https://sdk.zguiy.com/resurces/model/卷帘小.glb")
-kernel.model.add("小桌", "https://sdk.zguiy.com/resurces/model/小桌.glb")
+kernel.model.add({
+ modelId: "框架",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/框架.glb"
+});
+kernel.model.add({
+ modelId: "卷帘大",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/卷帘大.glb",
+ modelControlType: "rotation"
+});
+kernel.model.add({
+ modelId: "卷帘小",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/卷帘小.glb",
+ modelControlType: "rotation"
+});
+kernel.model.add({
+ modelId: "小桌",
+ modelUrl: "https://sdk.zguiy.com/resurces/model/小桌.glb",
+ modelControlType: "color"
+});
kernel.on('model:load:progress', (data) => {
console.log('模型加载事件', data);
@@ -64,7 +79,7 @@ let currentPickedMesh = null;
kernel.on('model:click', (data) => {
console.log('模型点击事件', data);
- console.log(data);
+ console.log('模型控制类型:', data.modelControlType);
// DOM 2D转3D 示例：点击模型时显示信息框
if (data.pickedMesh && data.pickedPoint) {
diff --git a/index.html b/index.html
index d924757..c89cdb7 100644
--- a/index.html
+++ b/index.html
@@ -315,7 +315,8 @@
名称: -
坐标: -
-
+
+
+
+
+
+
+
+