Track new features and enhancements to the STP file viewer
Fixed critical import and measurement issues, optimized file loading performance by up to 95%
2025/09/02
Platform stability achievement - resolving final integration issues and achieving remarkable performance gains:
This release addresses several critical issues that significantly impacted user experience:
Problem Solved: "Works first time, fails subsequently" issue completely resolved
window.OV object was incorrectly cleared during component cleanupProblem Solved: Measurement markers not appearing on 3D models
window.OV global objectProblem Solved: More menu button unresponsive on mobile devices in fullscreen mode
问题1："本地可用但线上不可用"故障
用户反馈现象:
根本原因分析: 通过系统化调试发现，问题源于37+个defer脚本在生产环境中的执行顺序不可预测：
// 问题代码（layout.tsx原始版本）
<script type="text/javascript" src="/js/o3dv.min.js" defer></script>
// defer导致脚本在DOM解析完成后异步执行，但执行顺序无法保证解决方案: 实现智能OV加载器，包含多重fallback机制：
// 解决方案（layout.tsx现有版本）
const fallbackFiles = [
'/js/o3dv.min.js',
'/js/o3dv.original.min.js',
'/js/o3dv.min.js.backup'
];
async function tryLoadOV() {
for (const file of fallbackFiles) {
try {
loadAttempt++;
await loadScript(file);
if (checkOV()) {
window.dispatchEvent(new CustomEvent('ovLoaded'));
return;
}
} catch (error) {
console.warn('Online3DViewer 文件加载失败:', file);
continue;
}
}
}效果验证:
问题2：全屏模式黑屏故障
现象描述:
根本原因分析:
通过详细调试发现，问题在于storeIsFullscreen依赖导致viewer在全屏切换时被不必要地重新初始化：
// 问题代码（viewer-view.tsx原始版本）
const getViewerBackgroundColor = useCallback((): [number, number, number] => {
const isDark = resolvedTheme === 'dark';
if (isDark) {
return storeIsFullscreen ? [15, 15, 15] : [10, 10, 10];
}
return storeIsFullscreen ? [250, 250, 250] : [255, 255, 255];
}, [resolvedTheme, storeIsFullscreen]); // ❌ storeIsFullscreen依赖导致重新初始化解决方案: 移除不必要的全屏状态依赖，使用静态颜色值：
// 解决方案（viewer-view.tsx现有版本）
const getViewerBackgroundColor = useCallback((): [number, number, number] => {
const isDark = resolvedTheme === 'dark';
if (isDark) {
return [10, 10, 10] as const;
}
return [255, 255, 255] as const;
}, [resolvedTheme]); // ✅ 移除storeIsFullscreen依赖，防止不必要的重新初始化关键修复位置: src/components/stp-viewer/viewer-view.tsx:248行
效果验证:
核心问题: 测量工具标记需要点击5-6次才显示，严重影响用户体验
调试历程 - 三个错误方向:
错误方向1: React渲染问题假设
错误方向2: THREE.js版本冲突假设
错误方向3: 占位对象创建
真正问题发现: 根本原因: THREE.js不在全局作用域
import * as THREE from 'three'最终解决方案:
// 在viewer-preloader.tsx中
const THREE = await import('three');
(window as any).THREE = THREE;
// 在MeasureToolCore.ts中
const getTHREE = () => {
if (typeof window !== 'undefined' && (window as any).THREE) {
return (window as any).THREE;
}
return null;
};效果验证:
调试策略改进:
开发最佳实践:
技术债务警示:
window.OVAchieved significant performance improvements in file loading:
Results: 60-95% performance improvement across all file sizes
| File Size | Before | After | Improvement |
|---|---|---|---|
| 1MB | 840ms | 39ms | 95.4% faster |
| 10MB | 1,380ms | 255ms | 81.5% faster |
| 100MB | 6,780ms | 2,415ms | 64.4% faster |
This release reinforced several important development principles:
window.OV should never be cleared in component cleanup背景: 基于用户需求建立左侧浮动分享工具条，经历了三个版本的关键架构演进
设计决策过程:
lg:block)/移动隐藏的设计权衡技术实现挑战:
/* 固定定位与层级管理 */
.floating-share-bar {
position: fixed;
left: 1rem;
top: 50%;
transform: translateY(-50%);
z-index: 40; /* 关键的层级设计 */
}关键技术决策:
scale(1.1)的交互反馈设计用户需求驱动:
技术实现复杂性:
// 状态管理挑战
const [showMoreDialog, setShowMoreDialog] = useState(false);
// More按钮的特殊处理
const platforms = [
// ... 现有7个平台
{
name: 'More',
isMore: true,
onClick: () => setShowMoreDialog(true)
}
];集成挑战:
问题诊断过程:
问题现象: 首页不显示FloatingShareBar
架构分析: FloatingShareBar被放置在ViewerView内部
状态依赖: ViewerView只在loading/viewing状态下渲染
首页状态: STPViewer默认为upload状态，显示UploadView
根本原因: FloatingShareBar在错误的组件层级当前架构问题:
首页 → HeroSection → HeroStpViewer → STPViewer
├── upload状态 → UploadView (无FloatingShareBar) ❌
├── loading状态 → ViewerView (有FloatingShareBar) ✅
└── viewing状态 → ViewerView (有FloatingShareBar) ✅解决方案架构:
STPViewer (新增FloatingShareBar层级)
├── upload状态 → UploadView + FloatingShareBar ✅
├── loading状态 → ViewerView + FloatingShareBar ✅
└── viewing状态 → ViewerView + FloatingShareBar ✅关键代码修改:
// src/components/stp-viewer/stp-viewer.tsx
return (
<div className={cn('stp-viewer-container', className)}>
{/* 状态相关的主要内容 */}
{renderContent()}
{/* 全局浮动分享工具条 */}
<FloatingShareBar file={viewerState.file} />
</div>
);对比分析方法: 通过系统化对比主页面模式vs全屏模式发现功能不一致：
| 功能 | 主页面模式 | 全屏模式 | 状态 |
|---|---|---|---|
| New File | ✅ | ✅ | 一致 |
| Screenshot | ✅ | ✅ | 一致 |
| Share | ❌ 缺失 | ✅ | 不一致 |
代码层面分析:
// viewer-view.tsx:730-766 - 主页面工具栏
const toolbarButtons: ToolbarButton[] = [
{ id: 'new-file', /* ... */ },
{ id: 'screenshot', /* ... */ },
// ❌ 缺少 Share 按钮
];
// FullscreenToolbar.tsx:132-139 - 全屏模式工具栏
const secondaryTools: ToolbarButton[] = [
{
id: 'share',
label: t('toolbar.share'),
// ✅ 已有但功能未实现
},
];技术限制的深度发现:
// ✅ React-Share 实际能力
- 链接分享: 所有平台都支持URL分享
- 文本内容: 支持标题、描述等文本参数
- 社交平台跳转: 打开平台官方分享页面
- 零外部依赖: 不需要加载第三方SDK
// ❌ React-Share 技术限制
- 不支持本地文件分享: 无法直接分享截图、文档等文件
- 不支持图片上传: 主流平台不支持直接上传图片
- 仅支持公网图片URL: 少数平台需要公网可访问图片链接
- 无后端功能: 无法处理文件上传、短链接生成开发计划的现实调整:
组件策略:
src/components/stp-viewer/
├── shared/
│ └── SimpleShareDialog.tsx # 统一分享对话框（唯一组件）
├── viewer-view.tsx # 添加Share按钮
└── fullscreen/
└── FullscreenToolbar.tsx # 连接实际分享功能设计原则的实践:
问题1: disabled按钮逻辑错误
// 错误逻辑
{
id: 'share',
disabled: !isViewerReady, // ❌ 分享页面链接不需要等待模型加载
}
// 正确逻辑
{
id: 'share',
disabled: false, // ✅ 页面分享功能应始终可用
}根本原因分析:
isViewerReady在模型加载前为false问题2: 平台支持不足的快速响应
第一阶段: 基础修复 (15分钟)
// src/components/stp-viewer/viewer-view.tsx:754
- disabled: !isViewerReady,
+ disabled: false,第二阶段: 平台扩展 (20分钟)
// 新增6个主流平台
const newPlatforms = [
'WhatsApp', // 全球最大即时通讯
'Telegram', // 技术用户群体偏爱
'Reddit', // 技术社区主要分享平台
'Pinterest', // 视觉内容分享，适合3D模型
'Weibo', // 中国用户主要社交平台
'Line', // 亚洲地区流行通讯应用
];第三阶段: 体验优化 (10分钟)
架构演进的重要性:
现实主义的技术选型:
快速响应的开发能力:
这个分享功能的开发历程展现了从架构演进到技术选型，从问题诊断到快速修复的完整开发智慧，为团队积累了宝贵的实战经验。
No breaking changes. All improvements are backward compatible. Users will experience:
Major code cleanup and performance improvements while maintaining 18-second loading performance
2025/08/28
Foundation solidification - optimizing the comprehensive feature set for long-term stability:
Comprehensive cleanup and optimization to improve maintainability and performance:
Professional model tree navigation with intelligent device-specific operation guides
2025/08/27
Revolutionary hierarchical model navigation that unlocks deep structural analysis capabilities, transforming complex STEP assemblies into manageable, navigable components.
Intelligent device-aware interface that provides contextual operation guidance:
useResponsive Hook for device detectionFixed long filename compression issue and improved mobile layout
2025/08/27
Professional mobile experience optimization - ensuring all advanced features work perfectly on touch devices:
Resolved the mobile toolbar issue where long filenames compressed tool buttons:
Universal file conversion with 17 import/10 export formats plus advanced material editing
2025/08/26
Revolutionary file format support that establishes STP Viewer as the most comprehensive online 3D file converter available.
CAD Formats: STEP, IGES, BREP, OCCT
Mesh Formats: STL, OBJ, OFF, PLY, 3DS
Modern Formats: GLTF/GLB, FBX, DAE, 3DM
Industry Formats: IFC, BIM, FCStd, SVG
Professional material editing and visualization capabilities:
Resolved critical user experience issues:
Revolutionary fullscreen mode framework - transforming STP Viewer into a professional 3D CAD platform
2025/08/25
This milestone marks the beginning of STP Viewer's transformation from a simple file viewer into a professional-grade 3D CAD visualization platform. We've laid the foundation for the most comprehensive online STEP file viewing experience ever created.
Progressive Feature Strategy: Two-tier experience design
// New component structure
src/components/stp-viewer/
├── fullscreen/ # Professional tools (lazy-loaded)
├── panels/ # Collapsible navigation panels
└── hooks/ # Custom hooks for 3D viewer integration"Simple by Default, Powerful by Choice"
| Experience Level | Interface | Use Case |
|---|---|---|
| Casual Users | Clean, minimal toolbar | Quick file preview, basic viewing |
| Professionals | Full CAD tool suite | Detailed analysis, measurements, exports |
This foundation enables the roadmap for:
This release establishes STP Viewer as the definitive online STEP file platform, setting new standards for:
The foundation is set. Next releases will add:
Welcome to the future of online STEP file visualization! 🎊
Revolutionary precision measurement tools with distance, angle, and parallel face measurements
2025/08/20
Introducing industry-grade measurement capabilities that transform STP Viewer into a precision analysis tool. This release brings CAD-level measurement accuracy to browser-based 3D visualization.
Focused refinements alongside the measurement system:
Revolutionary 3D navigation with 6 preset viewpoints, projection modes, and 30% faster loading
2025/08/15
Transforming 3D navigation from basic pan-and-zoom to professional CAD-level view control. This release brings industry-standard viewpoint management that rivals desktop CAD applications.
Perspective Projection (Default)
Orthographic Projection (Professional)
Significant optimizations alongside the new view system:
This release establishes desktop-class 3D navigation in the browser, making professional STEP file analysis accessible on any device. The foundation is set for advanced measurement, export, and analysis tools coming in future releases.
First version of the online STP file viewer with STEP format 3D preview
2025/08/01
We're excited to release the first version of STP Viewer with the following core features: