@qy_better_lib/hooks 0.2.10 → 0.2.11

package/DOCUMENTATION.md

@@ -256,7 +256,7 @@ close();
 
 ### 5. use-mqtt - MQTT功能
 
-> 注意：MQTT功能现在是可选依赖，需要单独导入
+> 注意：MQTT功能是可选依赖，需要单独导入
 
 #### 功能描述
 适用于需要MQTT通信的场景，支持连接管理、消息订阅和发布。
@@ -391,7 +391,7 @@ close(() => {
 
 ### 7. use-chart - 图表管理
 
-> 注意：图表管理功能现在是可选依赖，需要单独导入
+> 注意：图表管理功能是可选依赖，需要单独导入
 
 #### 功能描述
 适用于需要在前端使用ECharts的场景，支持图表渲染、主题切换、响应式设计等功能。
@@ -487,7 +487,7 @@ close(() => {
 
 ### 8. use-layout-flow - 流程图布局
 
-> 注意：流程图布局功能现在是可选依赖，需要单独导入
+> 注意：流程图布局功能是可选依赖，需要单独导入
 
 #### 功能描述
 适用于需要自动布局的流程图场景，支持多种布局方向和自定义元素。
@@ -623,12 +623,108 @@ emitter.on('test', (data) => {
 emitter.off('test', listener);
 ```
 
+### 10. use-three - Three.js 3D渲染
 
+> 注意：Three.js 3D渲染功能是可选依赖，需要单独导入
+
+#### 功能描述
+适用于需要在前端实现3D渲染的场景，基于Three.js库，支持场景管理、相机控制、光照系统、模型加载、交互系统等功能。
+
+#### 安装依赖
+```bash
+npm install three
+```
+
+#### 参数
+- `options: ThreeOption` - Three.js配置选项
+
+#### 返回值
+- **instance**: `ThreeTarget` - Three.js实例对象
+- **init_three**: `() => void` - 初始化Three.js场景
+- **set_container**: `(container: HTMLElement | string) => void` - 设置渲染容器
+- **create_perspective_camera**: `() => PerspectiveCamera` - 创建透视相机
+- **create_orthographic_camera**: `() => OrthographicCamera` - 创建正交相机
+- **set_camera_preset**: `(preset: string) => void` - 设置相机预设
+- **add_default_lighting**: `() => void` - 添加默认光照
+- **add_ambient_light**: `(options?: AmbientLightOptions) => AmbientLight` - 添加环境光
+- **add_directional_light**: `(options?: DirectionalLightOptions) => DirectionalLight` - 添加平行光
+- **add_point_light**: `(options?: PointLightOptions) => PointLight` - 添加点光源
+- **add_spot_light**: `(options?: SpotLightOptions) => SpotLight` - 添加聚光灯
+- **set_rendering_status**: `(status: boolean) => void` - 设置渲染状态
+- **set_target_fps**: `(fps: number) => void` - 设置目标帧率
+- **load_gltf_model**: `(url: string, options?: LoadModelOptions) => Promise<{ model: Object3D; animations: AnimationClip[]; }>` - 加载GLTF模型
+- **load_obj_model**: `(url: string, options?: LoadModelOptions) => Promise<Object3D>` - 加载OBJ模型
+- **enable_object_drag**: `(obj: Object3D, options?: DragOptions) => void` - 启用对象拖拽
+- **disable_object_drag**: `(obj: Object3D) => void` - 禁用对象拖拽
+- **enable_touch_support**: `() => void` - 启用触摸支持
+- **utils**: `ThreeUtils` - Three.js工具函数
+- **dispose_three**: `() => void` - 释放Three.js资源
+- **render**: `() => void` - 手动渲染
+- **get_select_object**: `(x: number, y: number) => Object3D | null` - 获取选中的对象
+- **enabled_vr**: `() => void` - 启用VR模式
+- **disabled_vr**: `() => void` - 禁用VR模式
+- **use_draco_loader**: `(path?: string) => void` - 使用DRACO压缩加载器
+- **reset**: `() => void` - 重置相机位置和控制器状态
+- **resize**: `() => void` - 调整渲染大小
+- **enable_shadow**: `() => void` - 启用阴影
+- **create_tool_tip**: `(obj: Object3D, options?: ToolTipOptions) => ObjectToolTip` - 创建3D对象工具提示
+- **create_tool_tip_instance**: `() => ObjectToolTip` - 创建ObjectToolTip实例
+- **create_box_helper**: `(color?: string) => BoxHelper` - 创建边界框辅助
+- **enable_effect**: `() => EffectComposer` - 启用后期处理
+- **enable_fxaa**: `() => ShaderPass` - 启用FXAA抗锯齿
+- **enable_unreal_bloom**: `(options?: BloomOptions) => UnrealBloomPass` - 启用UnrealBloom效果
+- **enable_outline**: `(options?: OutlineOptions) => OutlinePass` - 启用轮廓效果
+- **set_out_line**: `(obj: Object3D, visible: boolean) => void` - 设置对象轮廓
+
+#### 示例
+```typescript
+import { use_three } from '@qy_better_lib/hooks/use-three';
+
+// 初始化use-three
+const three = use_three({
+  scenebgcolor: '#f0f0f0',
+  camera_option: {
+    position: { x: 10, y: 10, z: 10 },
+    fov: 60
+  },
+  controls: true,
+  axes_helper: true,
+  default_lighting: true
+});
+
+// 设置容器
+three.set_container('#three-container');
+
+// 初始化场景
+three.init_three();
+
+// 添加模型
+await three.load_gltf_model('/models/model.glb', {
+  on_progress: (progress) => {
+    console.log('加载进度:', progress);
+  }
+});
+
+// 启用对象拖拽
+three.enable_object_drag(model);
+
+// 启用后期处理效果
+three.enable_effect();
+three.enable_unreal_bloom({
+  strength: 0.5,
+  radius: 1,
+  threshold: 0.1
+});
+
+// 释放资源
+// three.dispose_three();
+```
 
 ## 注意事项
 
-1. **use-chart** 现在是可选依赖，需要单独导入：`import { use_chart } from '@qy_better_lib/hooks/use-chart'`，并需要安装 ECharts 依赖：`npm install echarts`
-2. **use-layout-flow** 现在是可选依赖，需要单独导入：`import { use_layout_flow } from '@qy_better_lib/hooks/use-layout-flow'`，并需要安装 @antv/x6 和 dagre 依赖：`npm install @antv/x6 dagre`
-3. **use-mqtt** 现在是可选依赖，需要单独导入：`import { use_mqtt } from '@qy_better_lib/hooks/use-mqtt'`，并需要安装 mqtt 依赖：`npm install mqtt`
-4. **use-websocket** 需要确保服务器端支持 WebSocket 协议
-5. **use-print** 在某些浏览器中可能存在兼容性问题，建议在现代浏览器中使用
+1. **use-chart** 是可选依赖，需要单独导入：`import { use_chart } from '@qy_better_lib/hooks/use-chart'`，并需要安装 ECharts 依赖：`npm install echarts`
+2. **use-layout-flow** 是可选依赖，需要单独导入：`import { use_layout_flow } from '@qy_better_lib/hooks/use-layout-flow'`，并需要安装 @antv/x6 和 dagre 依赖：`npm install @antv/x6 dagre`
+3. **use-mqtt** 是可选依赖，需要单独导入：`import { use_mqtt } from '@qy_better_lib/hooks/use-mqtt'`，并需要安装 mqtt 依赖：`npm install mqtt`
+4. **use-three** 是可选依赖，需要单独导入：`import { use_three } from '@qy_better_lib/hooks/use-three'`，并需要安装 Three.js 依赖：`npm install three`
+5. **use-websocket** 需要确保服务器端支持 WebSocket 协议
+6. **use-print** 在某些浏览器中可能存在兼容性问题，建议在现代浏览器中使用

package/lib/use-three/interface.d.ts

@@ -1,7 +1,11 @@
 import { ThreeTarget } from '../shared/type';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { OutlinePass } from 'three/examples/jsm/postprocessing/OutlinePass.js';
+import { UnrealBloomPass } from 'three/examples/jsm/postprocessing/UnrealBloomPass.js';
 import { BoxHelper, Object3D } from 'three';
 import { ObjectToolTip, ToolTipOptions } from './toolTip';
+import { OutLineOptions } from './type';
 export interface UseThree {
     /**three 实例*/
     instance: ThreeTarget;
@@ -148,8 +152,53 @@ export interface UseThree {
      */
     create_tool_tip_instance: () => ObjectToolTip;
     /**
-       * 创建边界框辅助
-       * @param color 边界框颜色
-       */
-    create_box_helper: (color?: string) => BoxHelper;
+     * 创建边界框辅助
+     * @param color 边界框颜色
+     * @returns 边界框辅助对象
+     */
+    create_box_helper: (color?: string) => {
+        helper: BoxHelper;
+        add_to_scene: (scene: any) => void;
+        set_box_frame: (obj: Object3D) => void;
+        set_visible: (visible: boolean) => void;
+        destroy: () => void;
+    };
+    /**
+     * 开启后期处理
+     * @param use_ssao 是否使用SSAO效果
+     * @param ssao_options SSAO配置选项
+     * @returns EffectComposer实例
+     */
+    enable_effect: (use_ssao?: boolean, ssao_options?: {
+        kernel_radius?: number;
+        min_distance?: number;
+        max_distance?: number;
+    }) => EffectComposer | null;
+    /**
+     * 开启FXAA抗锯齿
+     * @param composer 后期处理composer
+     */
+    enable_fxaa: (composer: EffectComposer) => void;
+    /**
+     * 开启辉光光晕效果
+     * @param composer 后期处理composer
+     * @param strength 强度
+     * @param radius 半径
+     * @param threshold 阈值
+     * @returns UnrealBloomPass实例
+     */
+    enable_unreal_bloom: (composer: EffectComposer, strength?: number, radius?: number, threshold?: number) => UnrealBloomPass | null;
+    /**
+     * 开启轮廓高亮
+     * @param composer 后期处理composer
+     * @returns OutlinePass实例
+     */
+    enable_outline: (composer: EffectComposer) => OutlinePass | null;
+    /**
+     * 设置模型高光
+     * @param outline_pass OutlinePass实例
+     * @param objects 需要高光的模型
+     * @param out_line_options 配置
+     */
+    set_out_line: (outline_pass: OutlinePass, objects: Object3D[], out_line_options?: OutLineOptions) => void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qy_better_lib/hooks",
   "private": false,
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "qy better lib hooks",
   "author": "luhuiming",
   "license": "MIT",