Aggiungere riquadri secondari alla barra delle applicazioniPin secondary tiles to taskbar

Come per l'avvio dei riquadri secondari, è possibile aggiungere riquadri secondari alla barra delle applicazioni, in modo da consentire agli utenti di accedere rapidamente ai contenuti all'interno dell'app.Just like pinning secondary tiles to Start, you can pin secondary tiles to the taskbar, giving your users quick access to content within your app.

Taskbar pinning

Importante

API di accesso limitato: questa API è una funzionalità di accesso limitato.Limited Access API: This API is a limited access feature. Per usare questa API, contattare taskbarsecondarytile@microsoft.com .To use this API, please contact taskbarsecondarytile@microsoft.com.

Richiede l'aggiornamento del 2018 ottobre: per aggiungere la barra delle applicazioni, è necessario specificare come destinazione l'SDK 17763 ed eseguire build 17763 o versione successiva.Requires October 2018 Update: You must target SDK 17763 and be running build 17763 or higher to pin to taskbar.

Materiale sussidiarioGuidance

Un riquadro secondario consente agli utenti di accedere direttamente ad aree specifiche all'interno di un'app in modo coerente ed efficiente.A secondary tile provides a consistent, efficient way for users to directly access specific areas within an app. Anche se un utente sceglie se "aggiungere" un riquadro secondario alla barra delle applicazioni, le aree aggiungibili in un'app sono determinate dallo sviluppatore.Although a user chooses whether or not to "pin" a secondary tile to the taskbar, the pinnable areas in an app are determined by the developer. Per altre informazioni, vedere linee guida per i riquadri secondari.For more guidance, see Secondary tile guidance.

1. determinare se l'API esiste e sbloccare l'accesso limitato1. Determine if API exists and unlock Limited-Access

Per i dispositivi meno recenti non sono disponibili le API di blocco della barra delle applicazioni (se si usano versioni precedenti di Windows 10).Older devices don't have the taskbar pinning APIs (if you're targeting older versions of Windows 10). Pertanto, non è necessario visualizzare un pulsante pin su questi dispositivi che non sono in grado di bloccare.Therefore, you shouldn't display a pin button on these devices that aren't capable of pinning.

Questa funzionalità è inoltre bloccata con accesso limitato.Additionally, this feature is locked under Limited-Access. Per ottenere l'accesso, contattare Microsoft.To gain access, contact Microsoft. Le chiamate API a TaskbarManager. RequestPinSecondaryTileAsync, TaskbarManager. IsSecondaryTilePinnedAsync e TaskbarManager. TryUnpinSecondaryTileAsync avranno esito negativo con un'eccezione di accesso negato.API calls to TaskbarManager.RequestPinSecondaryTileAsync, TaskbarManager.IsSecondaryTilePinnedAsync, and TaskbarManager.TryUnpinSecondaryTileAsync will fail with an Access Denied exception. Le app non sono autorizzate a usare questa API senza autorizzazione e la definizione dell'API può cambiare in qualsiasi momento.Apps are not allowed to use this API without permission, and the API definition may change at any time.

Usare il metodo ApiInformation. IsMethodPresent per determinare se le API sono presenti.Use the ApiInformation.IsMethodPresent method to determine if the APIs are present. E quindi usare l'API LimitedAccessFeatures per provare a sbloccare l'API.And then use the LimitedAccessFeatures API to try unlocking the API.

if (ApiInformation.IsMethodPresent("Windows.UI.Shell.TaskbarManager", "RequestPinSecondaryTileAsync"))
{
    // API present!
    // Unlock the pin to taskbar feature
    var result = LimitedAccessFeatures.TryUnlockFeature(
        "com.microsoft.windows.secondarytilemanagement",
        "<tokenFromMicrosoft>",
        "<publisher> has registered their use of com.microsoft.windows.secondarytilemanagement with Microsoft and agrees to the terms of use.");

    // If unlock succeeded
    if ((result.Status == LimitedAccessFeatureStatus.Available) ||
        (result.Status == LimitedAccessFeatureStatus.AvailableWithoutToken))
    {
        // Continue
    }
    else
    {
        // Don't show pin to taskbar button or call any of the below APIs
    }
}

else
{
    // Don't show pin to taskbar button or call any of the below APIs
}

2. ottenere l'istanza di TaskbarManager2. Get the TaskbarManager instance

Le app di Windows possono essere eseguite su una vasta gamma di dispositivi. non tutte supportano la barra delle applicazioni.Windows apps can run on a wide variety of devices; not all of them support the taskbar. Al momento, solo i dispositivi desktop supportano la barra delle applicazioni.Right now, only Desktop devices support the taskbar. Inoltre, la presenza della barra delle applicazioni potrebbe andare avanti.Additionally, presence of the taskbar might come and go. Per verificare se la barra delle applicazioni è attualmente presente, chiamare il metodo TaskbarManager. GetDefault e verificare che l'istanza restituita non sia null.To check whether taskbar is currently present, call the TaskbarManager.GetDefault method and check that the instance returned is not null. Non visualizzare un pulsante pin se la barra delle applicazioni non è presente.Don't display a pin button if the taskbar isn't present.

Si consiglia di mantenere l'istanza per la durata di una singola operazione, ad esempio l'aggiunta, e quindi di catturare una nuova istanza la volta successiva che è necessario eseguire un'altra operazione.We recommend holding onto the instance for the duration of a single operation, like pinning, and then grabbing a new instance the next time you need to do another operation.

TaskbarManager taskbarManager = TaskbarManager.GetDefault();

if (taskbarManager != null)
{
    // Continue
}
else
{
    // Taskbar not present, don't display a pin button
}

3. verificare se il riquadro è attualmente aggiunto alla barra delle applicazioni3. Check whether your tile is currently pinned to the taskbar

Se il riquadro è già bloccato, è necessario visualizzare invece un pulsante Rimuovi.If your tile is already pinned, you should display an unpin button instead. È possibile usare il metodo IsSecondaryTilePinnedAsync per verificare se il riquadro è attualmente bloccato (gli utenti possono Rimuovi in qualsiasi momento).You can use the IsSecondaryTilePinnedAsync method to check whether your tile is currently pinned (users can unpin it at any time). In questo metodo, viene aggiunto il tileId del riquadro che si vuole visualizzare.In this method, you pass the TileId of the tile you want to know is pinned.

if (await taskbarManager.IsSecondaryTilePinnedAsync("myTileId"))
{
    // The tile is already pinned. Display the unpin button.
}

else 
{
    // The tile is not pinned. Display the pin button.
}

4. verificare se l'aggiunta è consentita4. Check whether pinning is allowed

L'aggiunta alla barra delle applicazioni può essere disabilitata da Criteri di gruppo.Pinning to the taskbar can be disabled by Group Policy. La proprietà TaskbarManager. IsPinningAllowed consente di controllare se l'aggiunta è consentita.The TaskbarManager.IsPinningAllowed property lets you check whether pinning is allowed.

Quando l'utente fa clic sul pulsante del PIN, è consigliabile controllare questa proprietà. se è false, verrà visualizzata una finestra di dialogo di messaggio che informa l'utente che il blocco non è consentito nel computer.When the user clicks your pin button, you should check this property, and if it's false, you should display a message dialog informing the user that pinning is not allowed on this machine.

TaskbarManager taskbarManager = TaskbarManager.GetDefault();
if (taskbarManager == null)
{
    // Display message dialog informing user that taskbar is no longer present, and then hide the button
}

else if (taskbarManager.IsPinningAllowed == false)
{
    // Display message dialog informing user pinning is not allowed on this machine
}

else
{
    // Continue pinning
}

5. costruire e aggiungere il riquadro5. Construct and pin your tile

L'utente ha fatto clic sul pulsante del PIN e si è determinato che le API sono presenti, la barra delle applicazioni è presente e l'aggiunta è consentita... tempo di aggiunta.The user has clicked your pin button, and you've determined that the APIs are present, taskbar is present, and pinning is allowed... time to pin!

Prima di tutto, creare il riquadro secondario come si farebbe per l'avvio.First, construct your secondary tile just like you would when pinning to Start. Per altre informazioni sulle proprietà dei riquadri secondari, vedere aggiungere riquadri secondari per avviare.You can learn more about the secondary tile properties by reading Pin secondary tiles to Start. Tuttavia, in caso di aggiunta alla barra delle applicazioni, oltre alle proprietà richieste in precedenza, è necessario anche Square44x44Logo (questo è il logo usato dalla barra delle applicazioni).However, when pinning to taskbar, in addition to the previously required properties, Square44x44Logo (this is the logo used by taskbar) is also required. In caso contrario, verrà generata un'eccezione.Otherwise, an exception will be thrown.

Passare quindi il riquadro al metodo RequestPinSecondaryTileAsync .Then, pass the tile to the RequestPinSecondaryTileAsync method. Poiché si tratta di un accesso limitato, non viene visualizzata una finestra di dialogo di conferma e non richiede un thread dell'interfaccia utente.Since this is under limited-access, this will not display a confirmation dialog and does not require a UI thread. In futuro, tuttavia, quando questo viene aperto oltre l'accesso limitato, i chiamanti che non utilizzano l'accesso limitato riceveranno una finestra di dialogo e saranno necessari per usare il thread dell'interfaccia utente.But in the future when this is opened up beyond limited-access, callers not utilizing limited-access will receive a dialog and be required to use the UI thread.

// Initialize the tile (all properties below are required)
SecondaryTile tile = new SecondaryTile("myTileId");
tile.DisplayName = "PowerPoint 2016 (Remote)";
tile.Arguments = "app=powerpoint";
tile.VisualElements.Square44x44Logo = new Uri("ms-appdata:///AppIcons/PowerPoint_Square44x44Logo.png");
tile.VisualElements.Square150x150Logo = new Uri("ms-appdata:///AppIcons/PowerPoint_Square150x150Logo.png");

// Pin it to the taskbar
bool isPinned = await taskbarManager.RequestPinSecondaryTileAsync(tile);

Questo metodo restituisce un valore booleano che indica se il riquadro è ora aggiunto alla barra delle applicazioni.This method returns a boolean value that indicates whether your tile is now pinned to the taskbar. Se il riquadro è già stato aggiunto, il metodo aggiorna il riquadro esistente e restituisce true.If your tile was already pinned, the method updates the existing tile and returns true. Se il blocco non è consentito o se la barra delle applicazioni non è supportata, il metodo restituisce false.If pinning wasn't allowed or taskbar isn't supported, the method returns false.

Enumera riquadriEnumerate tiles

Per visualizzare tutti i riquadri che sono stati creati e che sono ancora aggiunti in un punto qualsiasi (avvio, barra delle applicazioni o entrambi), usare FindAllAsync.To see all the tiles that you created and are still pinned somewhere (Start, taskbar, or both), use FindAllAsync. È quindi possibile controllare se questi riquadri sono aggiunti alla barra delle applicazioni e/o all'avvio.You can subsequently check whether these tiles are pinned to the taskbar and/or Start. Se la superficie non è supportata, questi metodi restituiscono false.If the surface isn't supported, these methods return false.

var taskbarManager = TaskbarManager.GetDefault();
var startScreenManager = StartScreenManager.GetDefault();

// Look through all tiles
foreach (SecondaryTile tile in await SecondaryTile.FindAllAsync())
{
    if (taskbarManager != null && await taskbarManager.IsSecondaryTilePinnedAsync(tile.TileId))
    {
        // Tile is pinned to the taskbar
    }

    if (startScreenManager != null && await startScreenManager.ContainsSecondaryTileAsync(tile.TileId))
    {
        // Tile is pinned to Start
    }
}

Aggiornare un riquadroUpdate a tile

Per aggiornare un riquadro già aggiunto, è possibile usare il metodo SecondaryTile. UpdateAsync come descritto in aggiornamento di un riquadro secondario.To update an already pinned tile, you can use the SecondaryTile.UpdateAsync method as described in Updating a secondary tile.

Rimuovi un riquadroUnpin a tile

L'app deve fornire un pulsante Rimuovi se il riquadro è attualmente bloccato.Your app should provide an unpin button if the tile is currently pinned. Per Rimuovi il riquadro, è sufficiente chiamare TryUnpinSecondaryTileAsync, passando il tileId del riquadro secondario che si vuole sbloccato.To unpin the tile, simply call TryUnpinSecondaryTileAsync, passing in the TileId of the secondary tile you would like unpinned.

Questo metodo restituisce un valore booleano che indica se il riquadro non è più aggiunto alla barra delle applicazioni.This method returns a boolean value that indicates whether your tile is no longer pinned to the taskbar. Se il riquadro non è stato aggiunto nella prima posizione, viene restituito anche true.If your tile wasn't pinned in the first place, this also returns true. Se l'operazione di sblocco non è consentita, restituisce false.If unpinning wasn't allowed, this returns false.

Se il riquadro è stato aggiunto solo alla barra delle applicazioni, il riquadro verrà eliminato perché non è più bloccato in un punto qualsiasi.If your tile was only pinned to taskbar, this will delete the tile since it is no longer pinned anywhere.

var taskbarManager = TaskbarManager.GetDefault();
if (taskbarManager != null)
{
    bool isUnpinned = await taskbarManager.TryUnpinSecondaryTileAsync("myTileId");
}

Eliminare un riquadroDelete a tile

Se si vuole Rimuovi un riquadro da qualsiasi posizione (inizio, barra delle applicazioni), usare il metodo requestDeleteAsync .If you want to unpin a tile from everywhere (Start, taskbar), use the RequestDeleteAsync method.

Questa operazione è appropriata per i casi in cui il contenuto aggiunto dall'utente non è più applicabile.This is appropriate for cases where the content the user pinned is no longer applicable. Ad esempio, se l'app consente di aggiungere un notebook per l'avvio e la barra delle applicazioni e quindi l'utente elimina il notebook, è sufficiente eliminare il riquadro associato al notebook.For example, if your app lets you pin a notebook to Start and taskbar, and then the user deletes the notebook, you should simply delete the tile associated with the notebook.

// Initialize a secondary tile with the same tile ID you want removed.
// Or, locate it with FindAllAsync()
SecondaryTile toBeDeleted = new SecondaryTile(tileId);

// And then delete the tile
await toBeDeleted.RequestDeleteAsync();

Rimuovi solo dall'inizioUnpin only from Start

Se si vuole solo Rimuovi un riquadro secondario dall'inizio lasciandolo sulla barra delle applicazioni, è possibile chiamare il metodo StartScreenManager. TryRemoveSecondaryTileAsync .If you only want to unpin a secondary tile from Start while leaving it on Taskbar, you can call the StartScreenManager.TryRemoveSecondaryTileAsync method. Questa operazione eliminerà in modo analogo il riquadro se non è più bloccato su altre superfici.This will similarly delete the tile if it is no longer pinned to any other surfaces.

Questo metodo restituisce un valore booleano che indica se il riquadro non è più bloccato per l'avvio.This method returns a boolean value that indicates whether your tile is no longer pinned to Start. Se il riquadro non è stato aggiunto nella prima posizione, viene restituito anche true.If your tile wasn't pinned in the first place, this also returns true. Se l'operazione di sblocco non è consentita o l'avvio non è supportato, viene restituito false.If unpinning wasn't allowed or Start isn't supported, this returns false.

await StartScreenManager.GetDefault().TryRemoveSecondaryTileAsync("myTileId");

RisorseResources