Arquivos e pastas nas bibliotecas Música, Fotos e VídeosFiles and folders in the Music, Pictures, and Videos libraries

Adicione pastas existentes de música, fotos ou vídeos às bibliotecas correspondentes.Add existing folders of music, pictures, or videos to the corresponding libraries. Você também pode remover pastas de bibliotecas, obter a lista de pastas em uma biblioteca e descobrir fotos, músicas e vídeos armazenados.You can also remove folders from libraries, get the list of folders in a library, and discover stored photos, music, and videos.

Uma biblioteca é uma coleção virtual de pastas, que contém uma pasta conhecida por padrão, além de outras pastas que o usuário tiver adicionado à biblioteca usando seu aplicativo ou um dos aplicativos nativos.A library is a virtual collection of folders, which includes a known folder by default plus any other folders the user has added to the library by using your app or one of the built-in apps. Por exemplo, a biblioteca Imagens inclui a pasta Imagens conhecida por padrão.For example, the Pictures library includes the Pictures known folder by default. O usuário pode adicionar pastas ou removê-las da biblioteca Imagens usando seu aplicativo ou o aplicativo Fotos nativo.The user can add folders to, or remove them from, the Pictures library by using your app or the built-in Photos app.

Pré-requisitosPrerequisites

  • Entender a programação assíncrona para aplicativos UWP (Plataforma Universal do Windows)Understand async programming for Universal Windows Platform (UWP) apps

    Você pode aprender a escrever aplicativos assíncronos em C# ou Visual Basic, consulte Chamar APIs assíncronas em C# ou Visual Basic.You can learn how to write asynchronous apps in C# or Visual Basic, see Call asynchronous APIs in C# or Visual Basic. Para saber como escrever aplicativos assíncronos em C++, consulte Programação assíncrona em C++.To learn how to write asynchronous apps in C++, see Asynchronous programming in C++.

  • Permissões de acesso ao localAccess permissions to the location

    No Visual Studio, abra o arquivo de manifesto do aplicativo no Designer de Manifesto.In Visual Studio, open the app manifest file in Manifest Designer. Na página Recursos, selecione as bibliotecas que seu aplicativo gerencia.On the Capabilities page, select the libraries that your app manages.

    • Biblioteca de MúsicasMusic Library
    • Biblioteca de ImagensPictures Library
    • Biblioteca de VídeosVideos Library

    Para saber mais, consulte Permissões de acesso a arquivo.To learn more, see File access permissions.

Obtenha uma referência a uma bibliotecaGet a reference to a library

Observação

Lembre-se de declarar a funcionalidade apropriada.Remember to declare the appropriate capability. Veja Declarações de funcionalidade de aplicativo para saber mais.See App capability declarations for more information.  

Para obter uma referência à biblioteca Música, Imagens ou Vídeo do usuário, chame o método StorageLibrary.GetLibraryAsync.To get a reference to the user's Music, Pictures, or Video library, call the StorageLibrary.GetLibraryAsync method. Forneça o valor correspondente da enumeração KnownLibraryId.Provide the corresponding value from the KnownLibraryId enumeration.

var myPictures = await Windows.Storage.StorageLibrary.GetLibraryAsync(Windows.Storage.KnownLibraryId.Pictures);

Obter a lista de pastas em uma bibliotecaGet the list of folders in a library

Para obter a lista de pastas em uma biblioteca, obtenha o valor da propriedade StorageLibrary.Folders.To get the list of folders in a library, get the value of the StorageLibrary.Folders property.

using Windows.Foundation.Collections;
IObservableVector<Windows.Storage.StorageFolder> myPictureFolders = myPictures.Folders;

Obter a pasta em uma biblioteca onde os novos arquivos são salvos por padrãoGet the folder in a library where new files are saved by default

Para obter a pasta em uma biblioteca onde os novos arquivos são salvos por padrão, obtenha o valor da propriedade StorageLibrary.SaveFolder.To get the folder in a library where new files are saved by default, get the value of the StorageLibrary.SaveFolder property.

Windows.Storage.StorageFolder savePicturesFolder = myPictures.SaveFolder;

Adicionar uma pasta existente a uma bibliotecaAdd an existing folder to a library

Para adicionar uma pasta a uma biblioteca, chame StorageLibrary.RequestAddFolderAsync.To add a folder to a library, you call the StorageLibrary.RequestAddFolderAsync. Considerando a biblioteca Imagens como um exemplo, chamar esse método faz com que um seletor de pasta seja mostrado para o usuário com um botão Adicionar essa pasta a Imagens .Taking the Pictures Library as an example, calling this method causes a folder picker to be shown to the user with an Add this folder to Pictures button. Se o usuário seleciona uma pasta, essa pasta permanecerá em seu local original no disco e se tornará um item na propriedade StorageLibrary.Folders (e no aplicativo Fotos nativo), mas a pasta não aparecerá como filho da pasta Imagens no Explorador de Arquivos.If the user picks a folder then the folder remains in its original location on disk and it becomes an item in the StorageLibrary.Folders property (and in the built-in Photos app), but the folder does not appear as a child of the Pictures folder in File Explorer.

Windows.Storage.StorageFolder newFolder = await myPictures.RequestAddFolderAsync();

Remover uma pasta de uma bibliotecaRemove a folder from a library

Para remover uma pasta de uma biblioteca, chame o método StorageLibrary.RequestRemoveFolderAsync e especifique a pasta a ser removida.To remove a folder from a library, call the StorageLibrary.RequestRemoveFolderAsync method and specify the folder to be removed. Você pode usar StorageLibrary.Folders e um controle ListView (ou semelhante) para o usuário selecionar uma pasta para remover.You could use StorageLibrary.Folders and a ListView control (or similar) for the user to select a folder to remove.

Quando você chama StorageLibrary.RequestRemoveFolderAsync, o usuário vê uma caixa de diálogo de confirmação dizendo que a pasta "não aparecerá mais em Imagens, mas não será excluída".When you call StorageLibrary.RequestRemoveFolderAsync, the user sees a confirmation dialog saying that the folder "won't appear in Pictures anymore, but won't be deleted." Isso significa que a pasta permanece em seu local original no disco, é removida da propriedade StorageLibrary.Folders e não será mais incluída no aplicativo Fotos nativo.What this means is that the folder remains in its original location on disk, is removed from the StorageLibrary.Folders property, and will no longer included in the built-in Photos app.

O exemplo a seguir supõe que o usuário selecionou a pasta a ser removida em um ListView controle chamado lvPictureFolders.The following example assumes that the user has selected the folder to remove from a ListView control named lvPictureFolders.

bool result = await myPictures.RequestRemoveFolderAsync(folder);

Receber notificações sobre mudanças na lista de pastas de uma bibliotecaGet notified of changes to the list of folders in a library

Para ser notificado sobre mudanças na lista de pastas de uma biblioteca, registre um manipulador para o evento StorageLibrary.DefinitionChanged da biblioteca.To get notified about changes to the list of folders in a library, register a handler for the StorageLibrary.DefinitionChanged event of the library.

myPictures.DefinitionChanged += MyPictures_DefinitionChanged;

void HandleDefinitionChanged(Windows.Storage.StorageLibrary sender, object args)
{
    // ...
}

Pastas de bibliotecas de mídiaMedia library folders

Um dispositivo fornece cinco locais predefinidos para usuários e aplicativos armazenarem arquivos de mídia.A device provides five predefined locations for users and apps to store media files. Aplicativos internos armazenam mídia baixada e mídia criada por usuários nesses locais.Built-in apps store both user-created media and downloaded media in these locations.

Os locais são:The locations are:

  • Pasta Imagens.Pictures folder. Contém imagens.Contains pictures.

    • Pasta Imagens da CâmeraCamera Roll folder. Contém fotos e vídeo da câmera interna.Contains photos and video from the built-in camera.

    • Pasta Imagens Salvas.Saved Pictures folder. Contém imagens que o usuário salvou de outros aplicativos.Contains pictures that the user has saved from other apps.

  • Pasta Música.Music folder. Contém músicas, podcasts e áudio livros.Contains songs, podcasts, and audio books.

  • Pasta Vídeo.Video folder. Contém vídeos.Contains videos.

Usuários e aplicativos também armazenam arquivos de mídia fora das pastas de bibliotecas de mídia no cartão SD.Users or apps may also store media files outside the media library folders on the SD card. Para localizar um arquivo de mídia confiavelmente no cartão SD, examine o conteúdo do cartão SD ou solicite ao usuário que localize o arquivo usando um seletor de arquivos.To find a media file reliably on the SD card, scan the contents of the SD card, or ask the user to locate the file by using a file picker. Para saber mais, consulte Acessar o cartão SD.For more info, see Access the SD card.

Consultando as bibliotecas de mídiaQuerying the media libraries

Para obter uma coleção de arquivos, especifique a biblioteca e o tipo de arquivos que você deseja.To get a collection of files, specify the library and the type of files that you want.

using Windows.Storage;
using Windows.Storage.Search;

private async void getSongs()
{
    QueryOptions queryOption = new QueryOptions
        (CommonFileQuery.OrderByTitle, new string[] { ".mp3", ".mp4", ".wma" });

    queryOption.FolderDepth = FolderDepth.Deep;

    Queue<IStorageFolder> folders = new Queue<IStorageFolder>();

    var files = await KnownFolders.MusicLibrary.CreateFileQueryWithOptions
      (queryOption).GetFilesAsync();

    foreach (var file in files)
    {
        // do something with the music files
    }
}

Os resultados da consulta incluem armazenamento interno e removívelQuery results include both internal and removable storage

Os usuários podem escolher armazenar arquivos de forma padrão no cartão SD opcional.Users can choose to store files by default on the optional SD card. Os aplicativos, entretanto, podem optar por não permitir que os arquivos sejam armazenados no cartão SD.Apps, however, can opt out of allowing files to be stored on the SD card. Com isso, as bibliotecas de mídia podem ficar divididas entre o armazenamento interno do dispositivo e o cartão SD.As a result, the media libraries can be split across the device's internal storage and the SD card.

Não é necessário gravar código adicional para ter essa possibilidade.You don't have to write additional code to handle this possibility. Os métodos no namespace Windows.Storage que consultam pastas conhecidas, combinam de forma transparente os resultados da consulta dos dois locais.The methods in the Windows.Storage namespace that query known folders transparently combine the query results from both locations. Você também não precisa especificar o recurso removableStorage no arquivo de manifesto do aplicativo para obter esses resultados combinados.You don't have to specify the removableStorage capability in the app manifest file to get these combined results, either.

Considere o estado do armazenamento do dispositivo mostrado na imagem a seguir:Consider the state of the device's storage shown in the following image:

imagens no telefone e no cartão SD

Se você consultar o conteúdo da Biblioteca de imagens chamando o await KnownFolders.PicturesLibrary.GetFilesAsync(), os resultados incluem ambos, internalPic.jpg e SDPic.jpg.If you query the contents of the Pictures Library by calling await KnownFolders.PicturesLibrary.GetFilesAsync(), the results include both internalPic.jpg and SDPic.jpg.

Trabalhando com fotosWorking with photos

Nos dispositivos em que a câmera salva imagens de baixa resolução e de alta resolução de cada imagem, as consultas avançadas retornam apenas a imagem de baixa resolução.On devices where the camera saves both a low-resolution image and a high-resolution image of every picture, the deep queries return only the low-resolution image.

As Imagens da câmera e a pasta Imagens salvas não oferecem suporte a consultas avançadas.The Camera Roll and the Saved Pictures folder do not support the deep queries.

Abrindo uma foto no aplicativo em que ela foi capturadaOpening a photo in the app that captured it

Se quiser permitir que o usuário abra novamente uma foto no aplicativo em que foi capturada, você pode salvar a CreatorAppId com os metadados da foto usando um código similar ao exemplo seguinte.If you want to let the user open a photo again later in the app that captured it, you can save the CreatorAppId with the photo's metadata by using code similar to the following example. Neste exemplo, testPhoto é um StorageFile.In this example, testPhoto is a StorageFile.

IDictionary<string, object> propertiesToSave = new Dictionary<string, object>();

propertiesToSave.Add("System.CreatorOpenWithUIOptions", 1);
propertiesToSave.Add("System.CreatorAppId", appId);

testPhoto.Properties.SavePropertiesAsync(propertiesToSave).AsyncWait();   

Usar métodos de fluxo para adicionar um arquivo a uma biblioteca de mídiaUsing stream methods to add a file to a media library

Ao acessar uma biblioteca de mídia usando uma pasta conhecida, como a KnownFolders.PictureLibrary, e utilizar métodos de fluxo para adicionar um arquivo a uma biblioteca de mídia, você deve certificar-se de fechar todos os fluxos que seu código abre.When you access a media library by using a known folder such as KnownFolders.PictureLibrary, and you use stream methods to add a file to the media library, you have to make sure to close all the streams that your code opens. Caso contrário, esses métodos falham ao adicionar um arquivo à biblioteca de mídia, pois ao menos uma transmissão ainda tem um identificador ao arquivo.Otherwise these methods fail to add the file to the media library as expected because at least one stream still has a handle to the file.

Como exemplo, ao executar o código a seguir, o arquivo não é adicionado à biblioteca de mídia.For example, when you run the following code, the file is not added to the media library. Na linha do código, using (var destinationStream = (await destinationFile.OpenAsync(FileAccessMode.ReadWrite)).GetOutputStreamAt(0)), os métodos OpenAsync e GetOutputStreamAt abrem um fluxo.In the line of code, using (var destinationStream = (await destinationFile.OpenAsync(FileAccessMode.ReadWrite)).GetOutputStreamAt(0)), both the OpenAsync method and the GetOutputStreamAt method open a stream. No entanto, somente o fluxo aberto pelo método GetOutputStreamAt é descartada como um resultado da instrução using.However only the stream opened by the GetOutputStreamAt method is disposed as a result of the using statement. O outro fluxo permanece aberto e impede que o arquivo seja salvo.The other stream remains open and prevents saving the file.

StorageFolder testFolder = await StorageFolder.GetFolderFromPathAsync(@"C:\test");
StorageFile sourceFile = await testFolder.GetFileAsync("TestImage.jpg");
StorageFile destinationFile = await KnownFolders.CameraRoll.CreateFileAsync("MyTestImage.jpg");
using (var sourceStream = (await sourceFile.OpenReadAsync()).GetInputStreamAt(0))
{
    using (var destinationStream = (await destinationFile.OpenAsync(FileAccessMode.ReadWrite)).GetOutputStreamAt(0))
    {
        await RandomAccessStream.CopyAndCloseAsync(sourceStream, destinationStream);
    }
}

Para usar métodos de transmissão com êxito ao adicionar um arquivo à biblioteca de mídia, certifique-se de fechar todos os fluxos abertos pelo seu código, como é mostrado no exemplo a seguir.To use stream methods successfully to add a file to the media library, make sure to close all the streams that your code opens, as shown in the following example.

StorageFolder testFolder = await StorageFolder.GetFolderFromPathAsync(@"C:\test");
StorageFile sourceFile = await testFolder.GetFileAsync("TestImage.jpg");
StorageFile destinationFile = await KnownFolders.CameraRoll.CreateFileAsync("MyTestImage.jpg");

using (var sourceStream = await sourceFile.OpenReadAsync())
{
    using (var sourceInputStream = sourceStream.GetInputStreamAt(0))
    {
        using (var destinationStream = await destinationFile.OpenAsync(FileAccessMode.ReadWrite))
        {
            using (var destinationOutputStream = destinationStream.GetOutputStreamAt(0))
            {
                await RandomAccessStream.CopyAndCloseAsync(sourceInputStream, destinationStream);
            }
        }
    }
}