{"_id":"@afilmory/webgl-viewer","_rev":"3-f0b484bfc02ff70b138bced0488e7499","name":"@afilmory/webgl-viewer","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.1":{"name":"@afilmory/webgl-viewer","version":"0.1.1","author":{"name":"Innei"},"license":"MIT","_id":"@afilmory/webgl-viewer@0.1.1","maintainers":[{"name":"innei","email":"tukon479@gmail.com"}],"dist":{"shasum":"6de946305b1a41c465c77e53c8fde0120af9ba7e","tarball":"https://registry.npmjs.org/@afilmory/webgl-viewer/-/webgl-viewer-0.1.1.tgz","fileCount":26,"integrity":"sha512-H9vF8j95MwmfwdKg9d4XDCvECTyLN0C1t1/V6W2QJBP86QTfqLV6WnI8YTa+z+xNapRl9YGTKMkBeTWa41+cCg==","signatures":[{"sig":"MEUCIQDXi3N7fliqavi5G+UXCbsy5Md0Be9efbhhq+hX6J24wAIgLg8ngvbAxWMNETM3TT5qw141I2EUp78ORBE664XxhrM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":147572},"main":"./dist/index.js","type":"module","_from":"file:afilmory-webgl-viewer-0.1.1.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"vite build","type-check":"tsc --noEmit"},"_npmUser":{"name":"innei","email":"tukon479@gmail.com"},"_resolved":"/private/var/folders/lh/pd33jhq91zqbgk8ktnz12j280000gp/T/a462f83dc59e5384e6bfd16dd3e358b1/afilmory-webgl-viewer-0.1.1.tgz","_integrity":"sha512-H9vF8j95MwmfwdKg9d4XDCvECTyLN0C1t1/V6W2QJBP86QTfqLV6WnI8YTa+z+xNapRl9YGTKMkBeTWa41+cCg==","_npmVersion":"10.2.4","description":"一个高性能的WebGL图片查看器React组件，支持超高分辨率图片的流畅缩放、平移和硬件加速渲染。","directories":{},"_nodeVersion":"22.15.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"6.3.5","nbump":"2.1.2","tsdown":"0.12.7","@types/react":"19.1.8","unplugin-dts":"1.0.0-beta.0","@microsoft/api-extractor":"7.52.8"},"peerDependencies":{"react":">=19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/webgl-viewer_0.1.1_1749736275953_0.3882133581167926","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@afilmory/webgl-viewer","version":"0.2.0","author":{"name":"Innei"},"license":"MIT","_id":"@afilmory/webgl-viewer@0.2.0","maintainers":[{"name":"innei","email":"tukon479@gmail.com"}],"dist":{"shasum":"727d680810e38b5ab8b3dd9c9932a315ead38419","tarball":"https://registry.npmjs.org/@afilmory/webgl-viewer/-/webgl-viewer-0.2.0.tgz","fileCount":25,"integrity":"sha512-Z/RdyAbtJAj/4q59aoJWudZHPdISqiNfcw6TR4U204VieSGL8kTnvrpgjKQUSaYVFqfc7MnQspNry8ucUqwq7g==","signatures":[{"sig":"MEUCIDzsftUmpcnR24mkpTFI8P3UOjgdfi2sIPWFI2cgpfkZAiEA4nyhshJ65UymXm3L8mwIY9RKacFJhKxp6myL9vfUVSc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":149292},"main":"./dist/index.js","type":"module","_from":"file:afilmory-webgl-viewer-0.2.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"vite build","type-check":"tsc --noEmit"},"_npmUser":{"name":"innei","actor":{"name":"innei","type":"user","email":"tukon479@gmail.com"},"email":"tukon479@gmail.com"},"_resolved":"/private/var/folders/lh/pd33jhq91zqbgk8ktnz12j280000gp/T/37fe7e606520c87556b63f624544a50e/afilmory-webgl-viewer-0.2.0.tgz","_integrity":"sha512-Z/RdyAbtJAj/4q59aoJWudZHPdISqiNfcw6TR4U204VieSGL8kTnvrpgjKQUSaYVFqfc7MnQspNry8ucUqwq7g==","_npmVersion":"10.2.4","description":"一个高性能的WebGL图片查看器React组件，支持超高分辨率图片的流畅缩放、平移和硬件加速渲染。","directories":{},"_nodeVersion":"22.15.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"6.3.5","nbump":"2.1.2","tsdown":"0.12.7","@types/react":"19.1.8","unplugin-dts":"1.0.0-beta.0","@microsoft/api-extractor":"7.52.8"},"peerDependencies":{"react":">=19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/webgl-viewer_0.2.0_1750149341177_0.32705810631107246","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-06-12T13:51:15.856Z","modified":"2026-04-25T13:30:52.603Z","0.1.1":"2025-06-12T13:51:16.174Z","0.2.0":"2025-06-17T08:35:41.340Z"},"author":{"name":"Innei"},"license":"MIT","description":"一个高性能的WebGL图片查看器React组件，支持超高分辨率图片的流畅缩放、平移和硬件加速渲染。","maintainers":[{"email":"npm@chralpha.com","name":"chralpha"},{"email":"tukon479@gmail.com","name":"innei"}],"readme":"# WebGL Image Viewer\n\n一个高性能的WebGL图片查看器React组件，支持超高分辨率图片的流畅缩放、平移和硬件加速渲染。\n\n## ✨ 特性\n\n- 🚀 **硬件加速**: 基于WebGL的GPU渲染，提供极致性能\n- 🖼️ **高分辨率支持**: 支持任意尺寸的图片，智能纹理管理\n- 📱 **跨平台兼容**: 支持桌面和移动设备的鼠标、触摸操作\n- 🎨 **平滑动画**: 物理感的缓动动画，提供流畅的用户体验\n- ⚡ **性能优化**: 渲染节流、防抖更新、内存管理\n- 🔧 **高度可配置**: 丰富的配置选项和回调函数\n- 🐛 **调试支持**: 内置调试模式，方便开发和优化\n- ✅ **完全可用**: 所有功能已实现并通过构建测试\n\n## 📦 安装\n\n```bash\nnpm install @afilmory/webgl-viewer\n# 或\nyarn add @afilmory/webgl-viewer\n# 或\npnpm add @afilmory/webgl-viewer\n```\n\n## 🚀 快速开始\n\n```tsx\nimport React from 'react'\nimport { WebGLImageViewer } from '@afilmory/webgl-viewer'\n\nfunction App() {\n  return (\n    <div style={{ width: '100vw', height: '100vh' }}>\n      <WebGLImageViewer\n        src=\"/path/to/your/image.jpg\"\n        className=\"image-viewer\"\n        onZoomChange={(originalScale, relativeScale) => {\n          console.log('Zoom changed:', { originalScale, relativeScale })\n        }}\n      />\n    </div>\n  )\n}\n```\n\n## 📁 项目架构\n\n重构后的项目采用模块化架构，每个文件都有明确的职责：\n\n```\nsrc/\n├── index.ts                    # 主入口文件，导出所有公共API\n├── types.ts                   # TypeScript类型定义\n├── constants.ts               # 常量配置和默认值\n├── utils.ts                   # 工具函数集合\n├── shaders.ts                 # WebGL着色器代码\n├── DebugInfo.tsx             # 调试信息React组件\n├── WebGLImageViewer.tsx      # 主要的React组件\n├── WebGLImageViewerEngine.ts # 完整的WebGL引擎实现\n└── example.tsx               # 使用示例\n```\n\n### 🏗️ 架构设计\n\n#### **单一职责原则**\n- `types.ts`: 完整的TypeScript类型定义和接口\n- `constants.ts`: 所有配置常量和默认值\n- `utils.ts`: 纯函数工具集，包含数学计算、设备检测等\n- `shaders.ts`: WebGL着色器源代码和编译工具\n- `DebugInfo.tsx`: 独立的调试信息显示组件\n- `WebGLImageViewer.tsx`: React组件包装器，处理生命周期\n- `WebGLImageViewerEngine.ts`: 核心WebGL引擎，包含所有功能实现\n\n#### **完整功能实现**\n- ✅ WebGL渲染管线完整实现\n- ✅ 图像加载和纹理管理\n- ✅ 鼠标和触摸事件处理\n- ✅ 平滑动画系统\n- ✅ 缩放和平移约束\n- ✅ 调试信息实时显示\n- ✅ 内存管理和资源清理\n- ✅ TypeScript类型安全\n\n## 🎯 核心功能\n\n### 交互支持\n- **鼠标操作**: 拖拽平移、滚轮缩放、双击切换\n- **触摸操作**: 单指拖拽、双指缩放、双击放大\n- **键盘操作**: 可扩展的键盘快捷键支持\n\n### 动画系统\n- **平滑缓动**: 使用四次方缓出函数\n- **可配置时长**: 支持自定义动画时间\n- **性能优化**: 60fps渲染节流控制\n\n### 约束系统\n- **边界限制**: 可选的图像边界约束\n- **缩放限制**: 可配置的最小/最大缩放比例\n- **智能居中**: 自动适应屏幕尺寸\n\n## 📚 API 文档\n\n### 基础属性\n\n| 属性 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `src` | `string` | **必需** | 图片源URL |\n| `className` | `string` | `\"\"` | CSS类名 |\n| `initialScale` | `number` | `1` | 初始缩放比例 |\n| `minScale` | `number` | `0.1` | 最小缩放比例 |\n| `maxScale` | `number` | `10` | 最大缩放比例 |\n\n### 交互配置\n\n```tsx\n// 滚轮配置\nwheel?: {\n  step: number              // 缩放步长，默认 0.1\n  wheelDisabled?: boolean   // 禁用滚轮，默认 false\n  touchPadDisabled?: boolean // 禁用触控板，默认 false\n}\n\n// 双指缩放配置\npinch?: {\n  step: number             // 缩放步长，默认 0.5\n  disabled?: boolean       // 禁用双指缩放，默认 false\n}\n\n// 双击配置\ndoubleClick?: {\n  step: number            // 缩放步长，默认 2\n  disabled?: boolean      // 禁用双击，默认 false\n  mode: 'toggle' | 'zoom' // 双击模式，默认 'toggle'\n  animationTime: number   // 动画时长，默认 200ms\n}\n\n// 拖拽配置\npanning?: {\n  disabled?: boolean        // 禁用拖拽，默认 false\n  velocityDisabled?: boolean // 禁用惯性，默认 true\n}\n```\n\n### 回调函数\n\n```tsx\n// 缩放变化回调\nonZoomChange?: (originalScale: number, relativeScale: number) => void\n\n// 图片复制完成回调\nonImageCopied?: () => void\n```\n\n### 组件引用方法\n\n```tsx\nconst viewerRef = useRef<WebGLImageViewerRef>(null)\n\n// 可用方法\nviewerRef.current?.zoomIn(true)      // 放大（可选动画）\nviewerRef.current?.zoomOut(false)    // 缩小（可选动画）\nviewerRef.current?.resetView()       // 重置视图\nviewerRef.current?.getScale()        // 获取当前缩放比例\n```\n\n## 🎮 使用示例\n\n### 基础使用\n```tsx\n<WebGLImageViewer\n  src=\"https://example.com/image.jpg\"\n  initialScale={1}\n  centerOnInit={true}\n/>\n```\n\n### 高级配置\n```tsx\n<WebGLImageViewer\n  src=\"https://example.com/large-image.jpg\"\n  minScale={0.1}\n  maxScale={20}\n  wheel={{ step: 0.05 }}\n  doubleClick={{ \n    mode: 'zoom', \n    step: 1.5,\n    animationTime: 300 \n  }}\n  onZoomChange={(original, relative) => {\n    console.log(`Zoom: ${relative.toFixed(2)}x`)\n  }}\n  debug={process.env.NODE_ENV === 'development'}\n/>\n```\n\n### 使用引用控制\n```tsx\nfunction ControlledViewer() {\n  const viewerRef = useRef<WebGLImageViewerRef>(null)\n  \n  return (\n    <>\n      <WebGLImageViewer\n        ref={viewerRef}\n        src=\"/image.jpg\"\n      />\n      <div>\n        <button onClick={() => viewerRef.current?.zoomIn(true)}>\n          放大\n        </button>\n        <button onClick={() => viewerRef.current?.zoomOut(true)}>\n          缩小\n        </button>\n        <button onClick={() => viewerRef.current?.resetView()}>\n          重置\n        </button>\n      </div>\n    </>\n  )\n}\n```\n\n## 🐛 调试功能\n\n启用 `debug={true}` 可显示实时调试信息：\n\n- **缩放信息**: 当前缩放比例和相对比例\n- **位置信息**: X/Y轴平移量\n- **Canvas信息**: 画布尺寸和设备像素比\n- **图像信息**: 原始图像尺寸\n- **性能信息**: WebGL最大纹理尺寸等\n\n```tsx\n<WebGLImageViewer\n  src=\"/image.jpg\"\n  debug={true}  // 显示调试面板\n/>\n```\n\n## ⚡ 性能特性\n\n### 渲染优化\n- **硬件加速**: 基于WebGL的GPU渲染\n- **渲染节流**: 16ms节流控制，维持60fps\n- **智能更新**: 防抖更新减少不必要的重绘\n\n### 内存管理\n- **自动清理**: 组件卸载时自动释放WebGL资源\n- **纹理优化**: 智能纹理尺寸计算\n- **事件清理**: 完整的事件监听器清理\n\n### 移动端优化\n- **触摸优化**: 原生触摸事件处理\n- **高DPI支持**: 自动适配Retina等高密度屏幕\n- **性能监控**: 移动设备性能信息记录\n\n## 🔧 开发指南\n\n### 构建项目\n```bash\nnpm run build\n```\n\n### 类型检查\n项目已完全实现TypeScript类型安全，所有API都有完整的类型定义。\n\n### 添加功能\n1. 在 `types.ts` 中定义新的类型接口\n2. 在 `constants.ts` 中添加相关配置常量\n3. 在 `WebGLImageViewerEngine.ts` 中实现功能逻辑\n4. 更新 `index.ts` 导出新的API\n\n## 📈 构建状态\n\n✅ **TypeScript编译**: 通过  \n✅ **类型检查**: 完整  \n✅ **构建输出**: \n- `dist/index.js` (39.49 kB, gzip: 11.06 kB)\n- `dist/index.d.ts` (16.41 kB, gzip: 5.87 kB)\n\n## 🔗 相关链接\n\n- [WebGL API 文档](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API)\n- [React Hooks 文档](https://reactjs.org/docs/hooks-intro.html)\n- [TypeScript 手册](https://www.typescriptlang.org/docs/)\n\n## 📄 许可证\n\n[MIT License](LICENSE) ","readmeFilename":"readme.md"}