DEV Community

flfljh
flfljh

Posted on

Development Practice for Screen Orientation Switching

Harmony OS Next

Development Practice for Screen Orientation Switching

Implementing screen orientation switching (landscape/portrait) in HarmonyOS application development requires attention to multiple aspects.

Window Rotation Strategy Selection

  1. Configuration in module.json5:

    Suitable for applications that determine orientation at launch. Examples:

    • Portrait-only apps: Configure "portrait"
    • Landscape-only apps: "landscape" (single orientation) or "auto_rotation_landscape" (supports normal/reverse landscape)
    • Rotatable apps: "auto_rotation_restricted"
    • Devices adapting to form factors: "follow_desktop" (phones in portrait, tablets/foldables in landscape when unfolded) Note: Configurations with "restricted" are controlled by the system's Rotation Lock toggle.

  2. setPreferredOrientation Method:

    Used for dynamically changing orientation after app launch (e.g., video/photo apps). Once set, the orientation persists across page navigation.

Landscape/Portrait Implementation for Video Apps

  1. Set Rotation Strategy:

    • Initialize with "follow_desktop" at launch
    • In video playback pages: 
     // Get window instance
 const window = getContext().windowStage.getMainWindowSync()
 // Set orientation based on user action (e.g., fullscreen button)
 window.setPreferredOrientation(display.Orientation.USER_ROTATION_LANDSCAPE)

  2. Monitor Window Changes:

   aboutToAppear() {
     window.on('windowSizeChange', (newSize) => {
       const isLandscape = newSize.width > newSize.height
       // Update UI layout
     })
   }
   aboutToDisappear() {
     window.off('windowSizeChange')
   }
Enter fullscreen mode Exit fullscreen mode

  1. Layout Adaptation:

    • Bind video player size to state variables: 
     @State playerWidth: number = 300
 @State playerHeight: number = 200

  • In windowSizeChange callback:

     if (isLandscape) {
   this.playerWidth = newSize.width
   this.playerHeight = newSize.height
 }
  1. Screen Lock Handling: 
   // Lock screen
   window.setPreferredOrientation(display.Orientation.AUTO_ROTATION_LANDSCAPE)

   // Unlock screen
   window.setPreferredOrientation(display.Orientation.AUTO_ROTATION_UNSPECIFIED)

   // Monitor Rotation Lock state
   settings.registerKeyObserver(settings.Key.KEY_ROTATION_LOCK, (locked) => {
     // Handle lock state changes
   })
Enter fullscreen mode Exit fullscreen mode

Landscape Implementation for Game Apps

  1. Landscape-Only:

    Configure "orientation": "landscape" in module.json5

  2. Support Reverse Landscape:

    Use "auto_rotation_landscape" or "auto_rotation_landscape_restricted" (respects system Rotation Lock)

  3. Portrait-to-Landscape Switching:

    Call setPreferredOrientation() when entering gameplay from portrait menus

Performance Optimization

  1. Component Freezing: 
   @Component({ freezeWhenInactive: true })
   struct DetailComponent {
     // UI won't update during rotation
   }
Enter fullscreen mode Exit fullscreen mode
  1. Image Auto-Resizing: 
   Image($r('app.media.cover'))
     .autoResize(true) // Reduces memory usage
Enter fullscreen mode Exit fullscreen mode
  1. Performance Pitfalls: Avoid:
    • Redundant onAreaChange listeners
    • Heavy visual effects (e.g., blur, complex gradients)
    • Unnecessary layout calculations during rotation

Common Issues & Solutions

  1. Tabs Visibility in Fullscreen Video: 
   Tabs() {
     // ...
   }
   .barHeight(this.isFullscreen ? 0 : 50) // Dynamically hide/show
Enter fullscreen mode Exit fullscreen mode

  1. Inconsistent Rotation Behavior:

    Set "orientation": "follow_desktop" in module.json5 for consistent behavior across devices

  2. Window Instance Delay:

    Use synchronous method:

   const window = getContext().windowStage.getMainWindowSync() // Avoid async delays
Enter fullscreen mode Exit fullscreen mode
  1. Rotation Lock Interaction: | System Setting | Restricted Config | Non-restricted Config | |----------------|-------------------|----------------------| | Rotation Lock ON | App won't rotate | App still rotates | | Rotation Lock OFF | App rotates | App rotates |

Top comments (0)