HarmonyOS 6学习：相机预览画面拉伸全解析——告别变形，打造完美相机预览体验

引言：当相机预览变成"哈哈镜"

你是否遇到过这样的尴尬场景？用户满怀期待地打开你的相机应用，准备记录美好瞬间，却发现预览画面像被"哈哈镜"扭曲了一样------人脸被拉长、建筑变形、圆形物体变成椭圆。用户皱眉退出，你的应用评分随之下降。这并非你的相机算法有问题，而是HarmonyOS相机预览中一个常见但容易被忽视的技术细节：预览流与输出流分辨率宽高比不一致。

本文将带你深入HarmonyOS 6相机系统的核心，从问题根源到实战解决方案，手把手教你如何让相机预览画面"回归真实"，打造媲美原生相机的完美体验。

一、问题重现：预览拉伸的"案发现场"

1.1 典型问题现象

用户在使用自定义相机应用时，预览画面出现明显的拉伸变形。具体表现为：

• 圆形物体在预览中显示为椭圆形

• 人脸比例失调，面部特征被拉长或压扁

• 建筑物线条不垂直，出现梯形失真

• 在不同屏幕比例的设备上，变形程度不一致

1.2 问题影响范围

设备类型	常见屏幕比例	拉伸风险等级
手机	19.5:9, 20:9	高
平板	4:3, 16:10	中
折叠屏	展开态多种比例	极高
智能手表	1:1, 圆形屏	特殊

二、技术原理：为什么预览会"变形"？

2.1 核心概念解析

要理解预览拉伸，首先需要掌握三个关键概念：

1. 预览流 (Preview Stream)

• 实时显示在屏幕上的视频流

• 分辨率通常较低以节省功耗

• 帧率较高以保证流畅性

2. 输出流 (Output Stream)

• 实际拍照或录像时捕获的数据流

• 分辨率较高以保证画质

• 帧率可能低于预览流

3. XComponent与Surface

• XComponent：HarmonyOS提供的图形绘制容器

• Surface：图形数据的承载面，由XComponent持有

• 两者宽高比必须一致，否则系统会自动进行非等比缩放

2.2 拉伸的根本原因

根据官方文档分析，问题的核心在于：预览流与输出流的分辨率宽高比不一致。

错误流程示意：

相机传感器 → 输出流(16:9) → 系统渲染 → 预览流(5:3) → 非等比缩放 → 画面拉伸

日志证据：

07-22 14:55:11.637 I {ValidateOutputProfile():4817} CaptureSession::ValidateOutputProfile profile:w(800),h(480),f(1003) outputType:0
07-22 14:55:50.463 I {ValidateOutputProfile():4817} CaptureSession::ValidateOutputProfile profile:w(1280),h(720),f(2000) outputType:1

• outputType:0：预览流，分辨率800×480，宽高比5:3

• outputType:1：输出流，分辨率1280×720，宽高比16:9

两者宽高比不一致，系统在渲染时进行非等比缩放，导致画面拉伸。

三、实战解决方案：三步告别预览拉伸

3.1 解决方案总览

解决预览拉伸问题的核心思路：让预览流、输出流、XComponent三者的宽高比保持一致。

graph TD
    A[问题: 预览画面拉伸] --> B{根本原因}
    B --> C[预览流与输出流宽高比不一致]
    C --> D[解决方案]
    D --> E[步骤1: 获取设备支持的分辨率]
    D --> F[步骤2: 计算最佳预览分辨率]
    D --> G[步骤3: 设置XComponent与Surface]
    E --> H[完美预览体验]
    F --> H
    G --> H

3.2 步骤一：获取设备支持的相机分辨率

首先需要获取相机硬件支持的所有分辨率，然后筛选出与屏幕宽高比最匹配的选项。

// CameraResolutionManager.ets - 相机分辨率管理工具类
import { camera } from '@kit.CameraKit';
import { BusinessError } from '@kit.BasicServicesKit';
import display from '@ohos.display';

export class CameraResolutionManager {
  // 获取设备屏幕宽高比
  static getScreenAspectRatio(): number {
    const displayInfo = display.getDefaultDisplaySync();
    const screenWidth = displayInfo.width;
    const screenHeight = displayInfo.height;
    return screenWidth / screenHeight;
  }
  
  // 获取相机支持的所有分辨率
  static async getSupportedResolutions(cameraId: string): Promise<Array<{width: number, height: number, aspectRatio: number}>> {
    try {
      const cameraManager = camera.getCameraManager();
      const cameraDevice = await cameraManager.getCameraDevice(cameraId);
      const profiles = cameraDevice.getSupportedSizes(camera.SceneMode.NORMAL_PHOTO);
      
      const resolutions: Array<{width: number, height: number, aspectRatio: number}> = [];
      
      for (let i = 0; i < profiles.length; i++) {
        const profile = profiles[i];
        const aspectRatio = profile.size.width / profile.size.height;
        
        resolutions.push({
          width: profile.size.width,
          height: profile.size.height,
          aspectRatio: aspectRatio
        });
      }
      
      // 按宽高比排序
      resolutions.sort((a, b) => a.aspectRatio - b.aspectRatio);
      
      return resolutions;
      
    } catch (err) {
      const error = err as BusinessError;
      console.error(`获取相机分辨率失败: ${error.code}, ${error.message}`);
      return [];
    }
  }
  
  // 根据屏幕宽高比选择最佳分辨率
  static selectBestResolution(
    resolutions: Array<{width: number, height: number, aspectRatio: number}>,
    targetAspectRatio: number,
    tolerance: number = 0.1
  ): {width: number, height: number, aspectRatio: number} | null {
    
    if (resolutions.length === 0) {
      return null;
    }
    
    // 1. 首先尝试找到宽高比完全匹配的
    for (const res of resolutions) {
      if (Math.abs(res.aspectRatio - targetAspectRatio) < 0.01) {
        return res;
      }
    }
    
    // 2. 在容忍范围内寻找最接近的
    let bestMatch: {width: number, height: number, aspectRatio: number} | null = null;
    let minDiff = Number.MAX_VALUE;
    
    for (const res of resolutions) {
      const diff = Math.abs(res.aspectRatio - targetAspectRatio);
      if (diff < tolerance && diff < minDiff) {
        minDiff = diff;
        bestMatch = res;
      }
    }
    
    // 3. 如果找不到，选择分辨率最高的
    if (!bestMatch) {
      bestMatch = resolutions.reduce((prev, current) => {
        return (prev.width * prev.height > current.width * current.height) ? prev : current;
      });
    }
    
    return bestMatch;
  }
}

3.3 步骤二：动态计算并设置预览参数

根据选定的分辨率，动态配置相机预览参数。

// CameraPreviewConfigurator.ets - 相机预览配置器
import { camera } from '@kit.CameraKit';
import { BusinessError } from '@kit.BasicServicesKit';

export class CameraPreviewConfigurator {
  private cameraManager: camera.CameraManager;
  private cameraInput: camera.CameraInput | undefined;
  private previewOutput: camera.PreviewOutput | undefined;
  private captureSession: camera.CaptureSession | undefined;
  
  constructor() {
    this.cameraManager = camera.getCameraManager();
  }
  
  // 配置相机预览
  async configureCameraPreview(
    cameraId: string,
    previewWidth: number,
    previewHeight: number,
    xComponentId: string
  ): Promise<boolean> {
    try {
      // 1. 获取相机设备
      const cameraDevice = await this.cameraManager.getCameraDevice(cameraId);
      
      // 2. 创建相机输入
      this.cameraInput = this.cameraManager.createCameraInput(cameraDevice);
      await this.cameraInput.open();
      
      // 3. 创建预览输出
      const previewProfile: camera.Profile = {
        size: { width: previewWidth, height: previewHeight },
        format: camera.PixelFormat.YCBCR_420_888
      };
      
      this.previewOutput = this.cameraManager.createPreviewOutput(previewProfile, xComponentId);
      
      // 4. 创建捕获会话
      this.captureSession = this.cameraManager.createCaptureSession();
      
      // 5. 配置会话
      await this.captureSession.beginConfig();
      await this.captureSession.addInput(this.cameraInput);
      await this.captureSession.addOutput(this.previewOutput);
      await this.captureSession.commitConfig();
      
      // 6. 启动预览
      await this.captureSession.start();
      
      console.info(`相机预览配置成功: ${previewWidth}x${previewHeight}`);
      return true;
      
    } catch (err) {
      const error = err as BusinessError;
      console.error(`相机预览配置失败: ${error.code}, ${error.message}`);
      this.releaseResources();
      return false;
    }
  }
  
  // 释放资源
  releaseResources() {
    if (this.captureSession) {
      this.captureSession.stop();
      this.captureSession.release();
      this.captureSession = undefined;
    }
    
    if (this.cameraInput) {
      this.cameraInput.close();
      this.cameraInput = undefined;
    }
    
    if (this.previewOutput) {
      this.previewOutput.release();
      this.previewOutput = undefined;
    }
  }
  
  // 动态调整预览尺寸（处理屏幕旋转等场景）
  async adjustPreviewSize(newWidth: number, newHeight: number): Promise<boolean> {
    if (!this.captureSession || !this.previewOutput) {
      return false;
    }
    
    try {
      await this.captureSession.stop();
      
      // 重新配置预览输出
      const newProfile: camera.Profile = {
        size: { width: newWidth, height: newHeight },
        format: camera.PixelFormat.YCBCR_420_888
      };
      
      // 注意：实际开发中需要重新创建previewOutput
      // 这里简化处理，实际应调用相应API更新
      
      await this.captureSession.start();
      return true;
      
    } catch (err) {
      const error = err as BusinessError;
      console.error(`调整预览尺寸失败: ${error.code}, ${error.message}`);
      return false;
    }
  }
}

3.4 步骤三：XComponent与Surface的完美匹配

确保XComponent的尺寸与Surface尺寸完全一致，这是避免拉伸的关键。

// PerfectCameraPreview.ets - 完整的相机预览组件
import { CameraResolutionManager } from './CameraResolutionManager';
import { CameraPreviewConfigurator } from './CameraPreviewConfigurator';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
export struct PerfectCameraPreview {
  private cameraConfigurator: CameraPreviewConfigurator = new CameraPreviewConfigurator();
  private xComponentController: XComponentController = new XComponentController();
  
  @State currentResolution: string = '正在检测...';
  @State isPreviewing: boolean = false;
  @State cameraId: string = '0'; // 默认后置摄像头
  
  // XComponent的尺寸状态
  @State xComponentWidth: number = 0;
  @State xComponentHeight: number = 0;
  
  aboutToAppear() {
    this.initializeCamera();
  }
  
  aboutToDisappear() {
    this.cameraConfigurator.releaseResources();
  }
  
  async initializeCamera() {
    try {
      // 1. 获取屏幕宽高比
      const screenAspectRatio = CameraResolutionManager.getScreenAspectRatio();
      console.info(`屏幕宽高比: ${screenAspectRatio.toFixed(3)}`);
      
      // 2. 获取相机支持的分辨率
      const resolutions = await CameraResolutionManager.getSupportedResolutions(this.cameraId);
      
      if (resolutions.length === 0) {
        this.currentResolution = '未找到支持的分辨率';
        return;
      }
      
      // 3. 选择最佳分辨率
      const bestResolution = CameraResolutionManager.selectBestResolution(
        resolutions,
        screenAspectRatio,
        0.15 // 15%的容忍度
      );
      
      if (!bestResolution) {
        this.currentResolution = '选择分辨率失败';
        return;
      }
      
      this.currentResolution = `${bestResolution.width}×${bestResolution.height} (${bestResolution.aspectRatio.toFixed(3)})`;
      
      // 4. 等待XComponent布局完成
      // 在实际开发中，需要通过onAreaChange获取实际尺寸
      
    } catch (err) {
      const error = err as BusinessError;
      console.error(`相机初始化失败: ${error.code}, ${error.message}`);
      this.currentResolution = '初始化失败';
    }
  }
  
  // XComponent区域变化回调
  onXComponentAreaChange(event: AreaChangeEvent) {
    const { width, height } = event.area;
    
    // 确保宽高有效
    if (width > 0 && height > 0) {
      this.xComponentWidth = width;
      this.xComponentHeight = height;
      
      console.info(`XComponent尺寸: ${width}x${height}`);
      
      // 可以在这里触发相机重新配置
      this.reconfigureCameraIfNeeded();
    }
  }
  
  async reconfigureCameraIfNeeded() {
    if (this.xComponentWidth === 0 || this.xComponentHeight === 0) {
      return;
    }
    
    // 计算XComponent的宽高比
    const xComponentAspectRatio = this.xComponentWidth / this.xComponentHeight;
    
    // 重新选择匹配的分辨率
    const resolutions = await CameraResolutionManager.getSupportedResolutions(this.cameraId);
    const bestResolution = CameraResolutionManager.selectBestResolution(
      resolutions,
      xComponentAspectRatio
    );
    
    if (bestResolution) {
      // 配置相机预览
      const success = await this.cameraConfigurator.configureCameraPreview(
        this.cameraId,
        bestResolution.width,
        bestResolution.height,
        'xcomponent_camera_preview'
      );
      
      this.isPreviewing = success;
    }
  }
  
  // 切换摄像头
  async switchCamera() {
    this.isPreviewing = false;
    this.cameraConfigurator.releaseResources();
    
    // 切换摄像头ID（简化处理，实际应查询可用摄像头）
    this.cameraId = this.cameraId === '0' ? '1' : '0';
    
    await this.initializeCamera();
    await this.reconfigureCameraIfNeeded();
  }
  
  build() {
    Column({ space: 20 }) {
      // 标题区域
      Text('完美相机预览')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .fontColor('#FFFFFF')
        .margin({ top: 40 })
      
      // 分辨率信息
      Text(`当前分辨率: ${this.currentResolution}`)
        .fontSize(14)
        .fontColor('#CCCCCC')
        .margin({ top: 10 })
      
      // 相机预览区域
      XComponent({
        id: 'xcomponent_camera_preview',
        type: 'surface',
        controller: this.xComponentController
      })
        .width('100%')
        .height('70%')
        .backgroundColor('#000000')
        .onAreaChange((event: AreaChangeEvent) => {
          this.onXComponentAreaChange(event);
        })
      
      // 控制区域
      Row({ space: 30 }) {
        Button(this.isPreviewing ? '停止预览' : '开始预览')
          .width(120)
          .backgroundColor(this.isPreviewing ? '#FF4D4F' : '#1890FF')
          .onClick(() => {
            if (this.isPreviewing) {
              this.cameraConfigurator.releaseResources();
              this.isPreviewing = false;
            } else {
              this.reconfigureCameraIfNeeded();
            }
          })
        
        Button('切换摄像头')
          .width(120)
          .backgroundColor('#52C41A')
          .onClick(() => {
            this.switchCamera();
          })
      }
      .margin({ top: 20 })
      
      // 提示信息
      Text('提示: 确保XComponent与预览流宽高比一致')
        .fontSize(12)
        .fontColor('#888888')
        .margin({ top: 30 })
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#1A1A1A')
    .padding(20)
  }
}

四、高级技巧与优化建议

4.1 处理屏幕旋转

屏幕旋转时，XComponent的宽高比会发生变化，需要动态调整预览分辨率。

// 监听屏幕旋转
import display from '@ohos.display';

// 在组件中添加旋转监听
aboutToAppear() {
  display.on('displayChange', () => {
    this.handleScreenRotation();
  });
}

async handleScreenRotation() {
  // 获取新的屏幕方向
  const displayInfo = display.getDefaultDisplaySync();
  const isLandscape = displayInfo.width > displayInfo.height;
  
  // 重新计算最佳分辨率
  await this.reconfigureCameraIfNeeded();
}

4.2 性能优化建议

1. 分辨率选择策略：

   • 优先选择与屏幕宽高比匹配的分辨率

   • 避免选择过高分辨率，减少GPU负担

   • 考虑设备性能，中低端设备使用较低分辨率

2. 内存管理：

   • 及时释放不再使用的Camera资源

   • 使用try-catch确保资源释放

   • 监控内存使用，防止泄漏

3. 用户体验优化：

   • 添加分辨率切换动画，避免画面跳动

   • 提供手动调整选项，满足专业用户需求

   • 在不同光照条件下测试预览效果

4.3 兼容性处理

不同设备、不同HarmonyOS版本可能有差异，需要做好兼容性处理。

// 兼容性检查工具
export class CameraCompatibilityChecker {
  static async checkCameraCapabilities(cameraId: string): Promise<{
    supportsAspectRatioMatch: boolean,
    maxPreviewWidth: number,
    maxPreviewHeight: number,
    supportedFormats: Array<string>
  }> {
    // 实际开发中需要查询设备能力
    // 这里返回示例数据
    return {
      supportsAspectRatioMatch: true,
      maxPreviewWidth: 3840,
      maxPreviewHeight: 2160,
      supportedFormats: ['YCBCR_420_888', 'RGBA_8888']
    };
  }
}

五、总结与展望

通过本文的学习，你已经掌握了解决HarmonyOS相机预览画面拉伸的完整方案。从问题定位到实战解决，关键在于理解预览流、输出流、XComponent三者的宽高比关系。

核心要点回顾：

1. 问题根源：预览流与输出流宽高比不一致导致非等比缩放

2. 解决方案：动态选择与屏幕宽高比匹配的预览分辨率

3. 关键步骤：获取支持分辨率 → 计算最佳匹配 → 配置XComponent

4. 注意事项：及时释放资源、处理屏幕旋转、做好兼容性

未来展望：

随着HarmonyOS生态的不断发展，相机API将更加完善。未来可能会有：

• 智能宽高比匹配算法

• 实时预览质量优化

• 多摄像头协同预览

• AI辅助的画面校正

从今天开始，让你的相机应用告别"哈哈镜"效果，为用户提供专业级的预览体验。当用户在你的应用中看到真实、无变形的预览画面时，他们会用更多的使用和更高的评分来回报你的用心。

记住：完美的相机预览，从正确的宽高比开始。