1# Class (MediaAlbumChangeRequest) 2<!--Kit: Media Library Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @yixiaoff--> 5<!--Designer: @liweilu1--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> - 本Class首批接口从API version 11开始支持。 13 14MediaAlbumChangeRequest implements [MediaChangeRequest](arkts-apis-photoAccessHelper-i.md#mediachangerequest11) 15 16相册变更请求。 17 18**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 19 20## 导入模块 21 22```ts 23import { photoAccessHelper } from '@kit.MediaLibraryKit'; 24``` 25 26## constructor<sup>11+</sup> 27 28constructor(album: Album) 29 30构造函数用于初始化新创建的对象。 31 32**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 33 34**参数：** 35 36| 参数名 | 类型 | 必填 | 说明 | 37| -------- | ------------------------- | ---- | ---------- | 38| album | [Album](arkts-apis-photoAccessHelper-Album.md) | 是 | 需要变更的相册。 | 39 40**错误码：** 41 42接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 43 44| 错误码ID | 错误信息 | 45| -------- | ---------------------------------------- | 46| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 47| 14000011 | System inner fail. | 48 49**示例：** 50 51phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 52 53```ts 54import { dataSharePredicates } from '@kit.ArkData'; 55 56async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 57 console.info('MediaAlbumChangeRequest constructorDemo'); 58 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 59 let fetchOptions: photoAccessHelper.FetchOptions = { 60 fetchColumns: [], 61 predicates: predicates 62 }; 63 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions); 64 let album: photoAccessHelper.Album = await fetchResult.getFirstObject(); 65 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 66} 67``` 68 69## getAlbum<sup>11+</sup> 70 71getAlbum(): Album 72 73获取当前相册变更请求中的相册。 74 75**注意**：对于创建相册的变更请求，在调用[applyChanges](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11)提交生效之前，该接口返回null。 76 77**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 78 79**返回值：** 80 81| 类型 | 说明 | 82| --------------------------------------- | ----------------- | 83| [Album](arkts-apis-photoAccessHelper-Album.md) | 返回当前相册变更请求中的相册。 | 84 85**错误码：** 86 87接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 88 89| 错误码ID | 错误信息 | 90| -------- | ---------------------------------------- | 91| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 92| 14000011 | System inner fail. | 93 94**示例：** 95 96phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 97 98```ts 99async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 100 console.info('getAlbumDemo'); 101 try { 102 // 请确保图库内存在用户相册。 103 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 104 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 105 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 106 let changeRequestAlbum: photoAccessHelper.Album = albumChangeRequest.getAlbum(); 107 console.info('change request album uri: ' + changeRequestAlbum.albumUri); 108 } catch (err) { 109 console.error(`getAlbumDemo failed with error: ${err.code}, ${err.message}`); 110 } 111} 112``` 113 114## setAlbumName<sup>11+</sup> 115 116setAlbumName(name: string): void 117 118设置相册名称。 119 120相册名参数规格： 121- 相册名字符串长度为1~255。 122- 不允许出现的非法英文字符，包括：<br> . \ / : * ? " ' ` < > | { } [ ] 123- 英文字符大小写不敏感。 124- 相册名不允许重名。 125 126**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 127 128**参数：** 129 130| 参数名 | 类型 | 必填 | 说明 | 131| ---------- | ------- | ---- | ---------------------------------- | 132| name | string | 是 | 待设置的相册名称。| 133 134**错误码：** 135 136接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 137 138| 错误码ID | 错误信息 | 139| -------- | ---------------------------------------- | 140| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 141| 14000011 | System inner fail. | 142 143**示例：** 144 145phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 146 147```ts 148async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 149 console.info('setAlbumNameDemo'); 150 try { 151 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 152 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 153 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 154 let newAlbumName: string = 'newAlbumName' + new Date().getTime(); 155 albumChangeRequest.setAlbumName(newAlbumName); 156 await phAccessHelper.applyChanges(albumChangeRequest); 157 console.info('setAlbumName successfully'); 158 } catch (err) { 159 console.error(`setAlbumNameDemo failed with error: ${err.code}, ${err.message}`); 160 } 161} 162``` 163 164## addAssets<sup>11+</sup> 165 166addAssets(assets: Array<PhotoAsset>): void 167 168向相册中添加资产。 169 170**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| ---------- | ------- | ---- | ---------------------------------- | 176| assets | Array<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | 是 | 待添加到相册中的资产数组。 | 177 178**错误码：** 179 180接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 181 182| 错误码ID | 错误信息 | 183| -------- | ---------------------------------------- | 184| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 185| 14000011 | System inner fail. | 186| 14000016 | Operation Not Support. | 187 188**示例：** 189 190phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 191 192```ts 193import { dataSharePredicates } from '@kit.ArkData'; 194 195async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 196 console.info('addAssetsDemo'); 197 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 198 let fetchOptions: photoAccessHelper.FetchOptions = { 199 fetchColumns: [], 200 predicates: predicates 201 }; 202 try { 203 // 请确保图库内存在用户相册和照片。 204 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 205 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 206 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 207 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 208 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 209 albumChangeRequest.addAssets([asset]); 210 await phAccessHelper.applyChanges(albumChangeRequest); 211 console.info('addAssets successfully'); 212 } catch (err) { 213 console.error(`addAssetsDemo failed with error: ${err.code}, ${err.message}`); 214 } 215} 216``` 217 218## removeAssets<sup>11+</sup> 219 220removeAssets(assets: Array<PhotoAsset>): void 221 222从相册中移除资产。 223 224**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 225 226**参数：** 227 228| 参数名 | 类型 | 必填 | 说明 | 229| ---------- | ------- | ---- | ---------------------------------- | 230| assets | Array<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | 是 | 待从相册中移除的资产数组。 | 231 232**错误码：** 233 234接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 235 236| 错误码ID | 错误信息 | 237| -------- | ---------------------------------------- | 238| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 239| 14000011 | System inner fail. | 240| 14000016 | Operation Not Support. | 241 242**示例：** 243 244phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 245 246```ts 247import { dataSharePredicates } from '@kit.ArkData'; 248 249async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 250 console.info('removeAssetsDemo'); 251 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 252 let fetchOptions: photoAccessHelper.FetchOptions = { 253 fetchColumns: [], 254 predicates: predicates 255 }; 256 try { 257 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 258 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 259 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions); 260 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 261 262 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 263 albumChangeRequest.removeAssets([asset]); 264 await phAccessHelper.applyChanges(albumChangeRequest); 265 console.info('removeAssets successfully'); 266 } catch (err) { 267 console.error(`removeAssetsDemo failed with error: ${err.code}, ${err.message}`); 268 } 269} 270``` 271