@ohos.file.volumeManager (卷管理)

该模块提供卷设备、磁盘设备查询和管理的相关功能：包括查询卷设备信息，对卷设备的挂载卸载、对磁盘设备分区以及卷设备的格式化等功能。说明：

• 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
• 本模块为系统接口。

官方文档：https://docs.openharmony.cn/pages/v5.1/zh-cn/application-dev/reference/apis-core-file-kit/js-apis-file-volumemanager-sys.md

1.volumemanager.getAllVolumes

getAllVolumes(): Promise<Array<Volume>>

异步获取当前外置存储中所有卷设备信息，以promise方式返回。

需要权限：ohos.permission.STORAGE_MANAGER

系统能力：SystemCapability.FileManagement.StorageService.Volume

返回值：

类型	说明
Promise<Volume[]>	Promise对象，返回当前所有可获得的卷设备信息。

2.volumemanager.mount

mount(volumeId: string): Promise<void>

异步挂载指定卷设备，以promise方式返回。当前仅支持vfat、exfat以及ntfs三种文件系统的卷设备挂载。

需要权限：ohos.permission.MOUNT_UNMOUNT_MANAGER

系统能力：SystemCapability.FileManagement.StorageService.Volume

参数：

参数名	类型	必填	说明
volumeId	string	是	卷设备id

返回值：

类型	说明
Promise	无返回结果的Promise对象

3.volumemanager.unmount

unmount(volumeId: string): Promise<void>

异步卸载指定卷设备，以promise方式返回。

需要权限：ohos.permission.MOUNT_UNMOUNT_MANAGER

系统能力：SystemCapability.FileManagement.StorageService.Volume

参数：

参数名	类型	必填	说明
volumeId	string	是	卷设备id

返回值：

类型	说明
Promise	无返回结果的Promise对象

4.volumemanager.format

format(volumeId: string, fsType: string): Promise<void>

异步对指定卷设备进行格式化，以promise方式返回。当前仅支持vfat和exfat两种文件系统类型的格式化，只有处于卸载状态的卷设备可以进行格式化，格式化后卷设备的uuid、挂载路径和卷设备描述均会发生变化。

需要权限：ohos.permission.MOUNT_FORMAT_MANAGER

系统能力：SystemCapability.FileManagement.StorageService.Volume

参数：

参数名	类型	必填	说明
volumeId	string	是	卷设备id
fsType	string	是	文件系统类型（vfat或者exfat）

返回值：

类型	说明
Promise	无返回结果的Promise对象

6.文件管理错误码

https://docs.openharmony.cn/pages/v5.1/zh-cn/application-dev/reference/apis-core-file-kit/errorcode-filemanagement.md

程序测试

1.准备工作

DevEco Studio测试系统接口的准备（应用权限与自动签名）

2.测试程序

import volumemanager from '@ohos.file.volumeManager';
import hilog from '@ohos.hilog';
import { BusinessError } from '@ohos.base';
import promptAction from '@ohos.promptAction';

// 定义SelectOption类型
interface SelectOption {
  value: string;
  label: string;
}

// 卷状态枚举
enum VolumeState {
  UNMOUNTED = 0,
  MOUNTED = 1,
  OTHER = -1
}

@Entry
@Component
struct Index {
  @State volumeInfo: string = '还没有获取卷信息';
  @State selectedVolumeId: string = '';
  @State selectedFsType: string = 'exfat';
  @State volumes: volumemanager.Volume[] = [];
  @State fsTypes: SelectOption[] = [
    { value: 'vfat', label: 'vfat' },
    { value: 'exfat', label: 'exfat' }
  ];

  async getVolumes(): Promise<void> {
    try {
      this.volumes = await volumemanager.getAllVolumes();
      hilog.info(0x0000, 'VOLUME', '获取卷信息: %{public}s', JSON.stringify(this.volumes));
      const volumesStr = JSON.stringify(this.volumes, null, 2);
      this.volumeInfo = volumesStr;

      if (this.volumes.length > 0 ) {
        this.selectedVolumeId = this.volumes[0].id;
      }

      hilog.info(0x0000, 'VOLUME', '获取卷信息: %{public}s', volumesStr);
    } catch (err) {
      const error = err as BusinessError;
      const errStr = `获取卷信息失败[${error.code}]: ${error.message || JSON.stringify(error)}`;
      this.volumeInfo = errStr;
      hilog.error(0x0000, 'VOLUME', '%{public}s', errStr);
    }
  }

  async mountVolume(volumeId: string): Promise<void> {
    if (!volumeId) {
      this.volumeInfo = '请先选择卷';
      return;
    }

    try {
      await volumemanager.mount(volumeId);
      const successMsg = `卷 ${volumeId} 挂载成功`;
      this.volumeInfo = successMsg;
      hilog.info(0x0000, 'VOLUME', successMsg);
    } catch (err) {
      const error = err as BusinessError;
      const errStr = `卷 ${volumeId} 挂载失败[${error.code}]: ${error.message || JSON.stringify(error)}`;
      this.volumeInfo = errStr;
      hilog.error(0x0000, 'VOLUME', '%{public}s', errStr);
    }
  }

  async unmountVolume(volumeId: string): Promise<void> {
    if (!volumeId) {
      this.volumeInfo = '请先选择卷';
      return;
    }

    try {
      await volumemanager.unmount(volumeId);
      const successMsg = `卷 ${volumeId} 卸载成功`;
      this.volumeInfo = successMsg;
      hilog.info(0x0000, 'VOLUME', successMsg);
    } catch (err) {
      const error = err as BusinessError;
      const errStr = `卷 ${volumeId} 卸载失败[${error.code}]: ${error.message || JSON.stringify(error)}`;
      this.volumeInfo = errStr;
      hilog.error(0x0000, 'VOLUME', '%{public}s', errStr);
    }
  }

  async formatVolume(volumeId: string, fsType: string): Promise<void> {
    if (!volumeId) {
      this.volumeInfo = '请先选择卷';
      return;
    }

    const isSupported = this.fsTypes.some(type => type.value === fsType);
    if (!isSupported) {
      this.volumeInfo = `不支持的文件系统类型，仅允许${this.fsTypes.map(t => t.value).join('、')}`;
      return;
    }

    const volume = this.volumes.find(v => v.id === volumeId);
    if (!volume || volume.state !== VolumeState.UNMOUNTED) {
      this.volumeInfo = '格式化失败：卷必须处于卸载状态才能格式化';
      return;
    }

    promptAction.showDialog({
      title: '警告',
      message: `确定要将卷 ${volumeId} 格式化为 ${fsType} 吗？\n这将删除所有数据！`,
      buttons: [
        { text: '取消', color: '#666666' },
        { text: '确认', color: '#F53F3F' }
      ]
    }).then(async (result) => {
      if (result.index === 1) {
        try {
          await volumemanager.format(volumeId, fsType);
          const successMsg = `卷 ${volumeId} 已成功格式化为 ${fsType} 文件系统`;
          this.volumeInfo = successMsg;
          hilog.info(0x0000, 'VOLUME', successMsg);
        } catch (err) {
          const error = err as BusinessError;
          const errStr = `卷 ${volumeId} 格式化失败[${error.code}]: ${error.message || JSON.stringify(error)}`;
          this.volumeInfo = errStr;
          hilog.error(0x0000, 'VOLUME', '%{public}s', errStr);
        }
      }
    });
  }

  build() {
    Column({ space: 20 }) {
      Button('获取卷信息')
        .width('50%')
        .height(50)
        .onClick(() => {
          this.getVolumes();
        })

      Button('挂载选中的卷')
        .width('50%')
        .height(50)
        .backgroundColor('#007DFF')
        .onClick(() => {
          this.mountVolume(this.selectedVolumeId);
        })

      Button('卸载选中的卷')
        .width('50%')
        .height(50)
        .backgroundColor('#F53F3F')
        .onClick(() => {
          this.unmountVolume(this.selectedVolumeId);
        })

      Row({ space: 10 }) {
        Text('文件系统类型:')
          .fontSize(14)
        // 修正Select组件的onSelect回调参数类型
        Select(this.fsTypes)
          .value(this.selectedFsType)
          .onSelect((index: number, value: string) => {  // 增加index参数
            this.selectedFsType = value;
          })
          .width(120)
      }

      Button('格式化选中的卷')
        .width('50%')
        .height(50)
        .backgroundColor('#FF7D00')
        .onClick(() => {
          this.formatVolume(this.selectedVolumeId, this.selectedFsType);
        })
        .enabled(this.selectedVolumeId !== '' &&
          this.volumes.find(v => v.id === this.selectedVolumeId)?.state === VolumeState.UNMOUNTED)

      Text('当前选中的卷ID: ' + this.selectedVolumeId)
        .fontSize(14)
        .fontColor('#666666')

    Text(this.volumeInfo)
      .fontSize(14)
      .lineHeight(20)
      .width('90%')
      .backgroundColor('#F5F5F5')
      .padding(10)
      .borderRadius(5)
      .textAlign(TextAlign.Start)  // 左对齐显示JSON内容
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }

  private getVolumeStateText(): string {
    if (!this.selectedVolumeId) return '未选择卷';

    const volume = this.volumes.find(v => v.id === this.selectedVolumeId);
    if (!volume) return '卷不存在';

    switch (volume.state) {
      case VolumeState.UNMOUNTED:
        return '已卸载（可格式化）';
      case VolumeState.MOUNTED:
        return '已挂载（不可格式化）';
      default:
        return `其他状态(${volume.state})`;
    }
  }

  private isUnmounted(): boolean {
    const volume = this.volumes.find(v => v.id === this.selectedVolumeId);
    return volume !== undefined && volume.state === VolumeState.UNMOUNTED;
  }
}