Cross-platform Compatibility Issues

This page collects common compatibility issues and solutions in uni-app cross-platform development.

Basic Compatibility Issues

Q: Inconsistent style appearance across platforms

Problem Description: The same style code displays differently on different platforms (e.g., WeChat Mini Program, H5, App).

Solutions:

1. Use flex layout to improve cross-platform consistency
2. Avoid using platform-specific style properties
3. Use conditional compilation to handle platform differences:

   /* #ifdef H5 */
   .box { width: 200px; }
   /* #endif */
   /* #ifdef MP-WEIXIN */
   .box { width: 200rpx; }
   /* #endif */

4. Use built-in style variables provided by uni-app

Q: Inconsistent font and icon display

Problem Description: Fonts and icons display differently across platforms.

Solutions:

1. Use generic font families (sans-serif, serif, etc.)
2. Use icon fonts (like iconfont) instead of image icons
3. Set different font sizes and line heights for specific platforms
4. Use icon components from uni-app component libraries

Q: Inconsistent page scrolling behavior

Problem Description: Page scrolling and elastic effects behave differently across platforms.

Solutions:

1. Use <scroll-view> component instead of native scrolling
2. Uniformly configure scroll parameters and behavior
3. Avoid using platform-specific scroll effects
4. Use conditional compilation to set different scroll parameters for different platforms

Functional Compatibility Issues

Q: APIs unavailable on certain platforms

Problem Description: Some APIs are unavailable or behave differently on specific platforms.

Solutions:

1. Use conditional compilation to handle platform differences:

   // #ifdef APP-PLUS
   // Code executed only on App platform
   // #endif
   // #ifdef H5
   // Code executed only on H5 platform
   // #endif

2. Use API fallback handling:

   // Prefer platform-specific API, fallback to common implementation
   function getLocation() {
     // #ifdef APP-PLUS
     return useAppLocationAPI();
     // #endif
     // #ifndef APP-PLUS
     return useCommonLocationAPI();
     // #endif
   }

3. Consult documentation to understand API differences across platforms
4. Use polyfills or custom implementations to fill missing functionality

Q: Components unavailable on certain platforms

Problem Description: Some components are unavailable or behave differently on specific platforms.

Solutions:

1. Use conditional compilation to load different component implementations for different platforms
2. Use cross-platform component libraries (like uni-ui)
3. Create custom components for cross-platform compatibility
4. Design different interaction methods for different platforms

Q: Event handling differences

Problem Description: Event triggering and handling differ across platforms.

Solutions:

1. Use uni-app's unified event handling approach
2. Avoid using platform-specific events
3. Provide unified handling logic for touch and mouse events
4. Use conditional compilation to handle platform-specific event differences

Platform-Specific Issues

Q: WeChat Mini Program specific issues

Problem Description: Specific compatibility issues encountered in WeChat Mini Program.

Solutions:

1. Follow WeChat Mini Program specifications and limitations
2. Pay attention to syntax differences between wxs and vue
3. Use conditional compilation to handle WeChat Mini Program specific logic
4. Understand and handle WeChat Mini Program page lifecycle differences

Q: H5 specific issues

Problem Description: Specific compatibility issues encountered on H5 platform.

Solutions:

1. Handle browser compatibility issues, especially for older browsers
2. Pay attention to CORS issues in H5
3. Use responsive design to adapt to different screen sizes
4. Handle H5-specific touch and mouse event differences

Q: App specific issues

Problem Description: Specific compatibility issues encountered on App platform.

Solutions:

1. Handle Android and iOS system differences
2. Pay attention to native component layering and occlusion issues
3. Handle App permission and system capability differences
4. Use conditional compilation to distinguish Android and iOS platforms:

   // #ifdef APP-PLUS-ANDROID
   // Android specific code
   // #endif
   // #ifdef APP-PLUS-IOS
   // iOS specific code
   // #endif

Layout and Style Compatibility

Q: rpx unit behavior across platforms

Problem Description: Inconsistent conversion and behavior of rpx units across platforms.

Solutions:

1. Understand rpx design principle: 1rpx = screen width/750
2. Avoid mixing rpx with other units
3. Consider using px units for elements requiring precise control
4. Use media queries to handle extreme screen sizes

Q: Safe area adaptation issues

Problem Description: Safe area adaptation issues for full-screen devices, notched screens, etc.

Solutions:

1. Use CSS variables to adapt to safe areas:

   .container {
     padding-bottom: env(safe-area-inset-bottom);
     padding-top: env(safe-area-inset-top);
   }

2. Use uni-app's system info API to get safe area dimensions
3. Avoid placing important content in areas that might be occluded
4. Design different layout schemes for different device types

Q: Flex layout compatibility issues

Problem Description: Flex layout behaves differently across platforms.

Solutions:

1. Use basic flex properties, avoid advanced features
2. Explicitly set dimensions and scaling behavior for flex children
3. Avoid complex nested flex layouts
4. Test and adjust flex layouts for specific platforms

Performance Compatibility Issues

Q: Large performance differences across platforms

Problem Description: Application runs smoothly on high-performance devices but lags on low-end devices.

Solutions:

1. Optimize rendering performance for low-end devices:
   • Reduce number of page elements
   • Optimize large list rendering
   • Reduce unnecessary animation effects
2. Use conditional compilation to provide different implementations for different performance levels
3. Implement performance degradation strategies, disable high-consumption features on low-end devices
4. Use uni.getSystemInfo() to get device information and adjust functionality accordingly

Q: Animation effect compatibility issues

Problem Description: Animation effects are inconsistent or have large performance differences across platforms.

Solutions:

1. Use simple CSS animations instead of complex animations
2. Avoid using extensive JS animations
3. Reduce or disable animations for low-end devices
4. Use conditional compilation to provide different animation implementations for different platforms

Debugging and Testing Techniques

Multi-platform Testing Strategy

1. Establish testing matrix covering main target platforms and devices
2. Prioritize testing platforms with largest user base
3. Use real device testing, don't rely solely on simulators
4. Design different test cases for different platforms

Effective Use of Conditional Compilation

1. Use conditional compilation to handle platform differences, not runtime judgment
2. Encapsulate platform-specific code as independent modules
3. Avoid overusing conditional compilation leading to unmaintainable code
4. Use unified interfaces to encapsulate platform differences

Compatibility Issue Troubleshooting Process

1. Determine specific platform and conditions where problem occurs
2. Create minimal reproduction example
3. Consult documentation to understand platform limitations and differences
4. Find alternative implementations or fallback solutions
5. Test solutions on all target platforms

Best Practices

Design Phase

1. Understand design specifications and limitations of each target platform
2. Consider cross-platform compatibility during design, avoid platform-specific interaction patterns
3. Design alternative solutions for different platforms
4. Prioritize using common components and interaction patterns

Development Phase

1. Follow uni-app development specifications
2. Use cross-platform component libraries
3. Avoid direct DOM manipulation
4. Encapsulate platform differences, provide unified interfaces

Testing Phase

1. Test on multiple devices and platforms
2. Focus on edge cases and extreme conditions
3. Test performance under different network conditions
4. Collect user feedback for continuous improvement

Release Phase

1. Develop different release strategies for different platforms
2. Use gradual rollout to reduce risks
3. Establish monitoring systems to detect issues promptly
4. Prepare contingency plans for platform-specific issues

If you cannot find a solution to your problem on this page, please check the uni-app official documentation or ask questions on the uni-app official forum.