Panoramica e note sulla versione: Libreria dell'interfaccia utente di Windows 3 - Project Reunion 0.8 Preview (maggio 2021)

  • Articolo

Windows UI Library (WinUI) 3 è un framework nativo per l'esperienza utente (UX) per la creazione di app di Windows moderne. Viene fornito indipendentemente dal sistema operativo Windows come parte di Project Reunion (ora chiamato Windows App SDK). La versione 0.8 Preview fornisce modelli WinUI 3 in Visual Studio per iniziare a creare app con un'interfaccia utente basata su WinUI 3.

WinUI 3 - Project Reunion 0.8 Preview è una versione non definitiva di WinUI 3 che include correzioni di bug, miglioramenti generali e funzionalità sperimentali, alcune delle quali saranno stabilizzate per la versione stabile di Windows App SDK 0.8 nel giugno 2021.

Importante

Questa versione di anteprima è destinata a una valutazione preliminare e a raccogliere feedback dalla community di sviluppatori. NON deve essere usato per le app di produzione.

Se stai cercando di distribuire un'app di produzione usando Project Reunion e WinUI 3, vedi Panoramica e note sulla versione: WinUI 3 - Project Reunion 0.5.

Usare il repository GitHub per WinUI per fornire commenti e registrare suggerimenti e problemi.

Nota

Project Reunion è il nome di codice precedente per Windows App SDK. Questa documentazione usa ancora Project Reunion quando si fa riferimento alle versioni precedenti che usavano questo nome di codice.

Installare WinUI 3 - Project Reunion 0.8 Preview

Questa versione di WinUI 3 è disponibile come parte dell'anteprima di Project Reunion 0.8. Per installare, vedere:

Installare gli strumenti per i canali di anteprima e sperimentali di Windows App SDK

Poiché WinUI viene fornito come parte di Project Reunion, si scaricherà Project Reunion Visual Studio Extension (VSIX) per iniziare, che include un set di strumenti e componenti di sviluppo. Per ulteriori informazioni sul pacchetto Project Reunion, vedere Distribuire app che usano Windows App SDK. Windows App SDK VSIX include modelli WinUI 3 in Visual Studio che verranno usati per compilare l'app WinUI 3.

Nota

Per visualizzare i controlli e le funzionalità winUI 3 in azione, è possibile clonare e compilare la raccolta di controlli WinUI 3 da GitHub oppure scaricarla da Microsoft Store.

Dopo aver configurato l'ambiente di sviluppo, vedere Modelli winUI 3 in Visual Studio per acquisire familiarità con i modelli di progetto e di elementi di Visual Studio disponibili.

Per altre informazioni su come iniziare a creare un'app WinUI 3, vedere gli articoli seguenti:

A parte le limitazioni e i progetti noti, la creazione di un'app con i progetti WinUI è analoga alla creazione di un'app UWP con XAML e WinUI 2.x. Sono pertanto applicabili quasi tutte le linee guida per le app UWP e gli spazi dei nomi WinRT Windows.UI in Windows SDK.

La documentazione di riferimento dell'API WinUI 3 è disponibile qui: Informazioni di riferimento sulle API WinUI 3

WebView2

Per usare WebView2 con questa versione di WinUI 3, scaricare il programma di installazione di Evergreen Bootstrapper o Il programma di installazione autonomo Evergreen sempre disponibile in questa pagina se non è già installato il runtime WebView2.

Toolkit della Community Windows

Se si usa Windows Community Toolkit, scaricare la versione più recente.

Supporto di Visual Studio

Per usufruire dei vantaggi offerti dalle funzionalità di strumenti più recenti introdotte in WinUI 3, ad esempio Ricaricamento rapido, Albero degli elementi visivi attivi ed Esplora proprietà attive, è necessario usare una versione di anteprima di Visual Studio 2019 16.10. Si noti che le versioni di anteprima di Visual Studio sono prodotti non definitivi, pertanto è possibile che si verifichino bug e limitazioni quando si usano versioni di anteprima di Visual Studio per compilare app WinUI 3.

La tabella seguente illustra la compatibilità delle versioni di Visual Studio 2019 con WinUI 3 - Project Reunion 0.5.

Versione di Visual Studio WinUI 3 - Project Reunion 0.5
16.8 No
16.9 Sì, ma senza ricaricamento rapido, albero degli elementi visivi attivi o Esplora proprietà attive
16.10 (versioni di anteprima) Sì, con tutti gli strumenti winUI 3 (in anteprima)

Aggiornamento dell'app WinUI 3 esistente

Se hai creato un'app con una versione di anteprima o stabile precedente di WinUI 3, puoi aggiornare il progetto per usare WinUI 3 - Project Reunion 0.8 Preview. Per istruzioni, vedere Aggiornare i progetti esistenti alla versione più recente di Project Reunion.

Modifiche principali introdotte in questa versione

  • Il controllo pivot è ora disponibile per l'uso in questa versione.
  • La maggior parte delle correzioni di bug critiche delle versioni di manutenzione di Project Reunion v0.5.5, v0.5.6 e v0.5.7 sono incluse anche in questa versione. Per le correzioni di manutenzione che non sono state inserito in questa anteprima, vedere Problemi noti.

Elenco dei bug risolti in WinUI 3 - Project Reunion 0.8 Preview

  • x:Bind non funziona in un oggetto MenuFlyoutItem personalizzato (in genere x:Bind in ControlTemplate non funziona se l'ambito dei nomi padre usa anche x:Bind)

  • Nascondi popup finestra quando si sposta la finestra di primo livello (o isola)

  • Pagina StandardUICommand in WinUI 3 Controls Gallery non visualizza tutti gli elementi

  • Fare clic con il pulsante destro del mouse in TextBox provoca l’arresto anomalo dell'applicazione

  • Menu di scelta rapida visualizzato nella posizione errata per EditableComboBox

  • La modifica della selezione richTextBlock con il tocco rende l'indicatore di selezione non disponibile

  • Eccezione Microsoft C++: winrt::hresult_error in posizione di memoria 0x... quando viene usato navigationView

  • Il messaggio di errore winUI 3 richiede la riformulazione: "Impossibile risolvere ‘Windows.metadata’. Installare Windows Software Development Kit. Windows SDK viene installato con Visual Studio".

  • L'eccezione Setter VSM per la generazione di eccezioni ha una logica all'indietro

  • Spostare lo stato attivo su WebView2 (se necessario) quando il processo del browser si arresta in modo anomalo

  • ProgressBar non mostra la differenza tra l'opzione Paused e Error

  • PointerReplay in esecuzione costante

  • NavigationView causa un arresto anomalo nella piattaforma UWP, Reunion 0.5 Preview

  • AutoSuggestBox, ComboBox e CommandBarFlyout non impostano ShouldConstrainToRootBounds="false" nel popup

  • WinUI 3 - Project Reunion 0.5 che genera eccezioni C++ per un'app gestita C#

  • Lo stato attivo iniziale della scheda WebView2 è andato perso

  • WebView2 si arresta in modo anomalo quando i valori DPI cambiano dopo Close()

  • Modifica dell'aspetto di AppBarButton con riquadro a comparsa su CommandBar in WinUI3

Nuove caratteristiche e funzionalità introdotte nelle versioni di anteprima precedenti di WinUI 3

Le seguenti caratteristiche e funzionalità sono state introdotte nelle versioni precedenti dell'anteprima di WinUI 3 e continuano a essere supportate in WinUI 3 - Project Reunion 0.8 Preview.

Nota

Alcune delle funzionalità seguenti continueranno a far parte delle anteprime di WinUI 3, ma potrebbero non far parte della prossima versione supportata. Queste funzionalità vengono contrassegnate come sperimentali e generano un avviso quando vengono usate in un'app. Anche le API che fanno parte della versione non definitiva di WinUI 2.6 sono contrassegnate come sperimentali in questa versione.

  • Possibilità di creare app desktop con WinUI, tra cui .NET per le app Win32
  • Supporto a livello di anteprima per la creazione di app UWP
  • RadialGradientBrush
  • Aggiornamenti di TabView
  • Aggiornamenti del tema scuro
  • Miglioramenti e aggiornamenti per WebView2
    • Supporto per valori DPI alti
    • Supporto per il ridimensionamento e lo spostamento di finestre
    • Aggiornamento per usare come destinazione la versione più recente di Microsoft Edge
    • Eliminazione della necessità di fare riferimento al pacchetto NuGet specifico di WebView2
  • SwapChainPanel
  • Supporto di MRT Core
    • Con questo supporto le app risultano più veloci e snelle all'avvio ed è possibile cercare le risorse più rapidamente.
  • Supporto di Arm64
  • Trascinamento della selezione all'interno e all'esterno delle app
  • RenderTargetBitmap (attualmente solo contenuto XAML, nessun contenuto SwapChainPanel)
  • Supporto del cursore personalizzato
  • Input su thread separato
  • Miglioramenti dell'esperienza degli strumenti e degli sviluppatori:
    • Albero degli elementi visivi attivi, Ricaricamento rapido, Esplora proprietà attive e strumenti simili
    • IntelliSense per WinUI 3
  • Miglioramenti necessari per la migrazione all'open source
  • Funzionalità della barra del titolo personalizzate: nuove API Window.ExtendsContentIntoTitleBar e Window.SetTitleBar che consentono agli sviluppatori di creare barre del titolo personalizzate nelle app desktop.
  • VirtualSurfaceImageSource support
  • Acrilico in-app
  • Supporto per più finestre nelle app desktop
  • Convalida dell'input

Feedback e suggerimenti

Invia il tuo feedback nel repository GitHub di WinUI.

Limitazioni e problemi noti

L'anteprima di WinUI 3 - Project Reunion 0.8 è solo quella, un'anteprima. Sono quindi previsti bug, limitazioni e altri problemi.

Di seguito sono riportati alcuni problemi noti di WinUI 3 Preview 0.8. Se si riscontra un problema non elencato, è possibile segnalarlo aggiungendolo a un problema esistente o inserendone uno nuovo tramite il repository GitHub di WinUI.

Supporto della piattaforma e del sistema operativo

WinUI 3 - Project Reunion 0.8 Preview è compatibile con i PC che eseguono l'aggiornamento di Windows 10 di ottobre 2018 (versione 1809 - build 17763) e versioni successive.

Strumenti di sviluppo

  • Sono supportate solo le app C# e C++/WinRT.
  • Le app desktop supportano .NET 6 (e successive) e C# 9 e devono essere assemblate in un'app MSIX.
  • Nessun supporto per la finestra di progettazione XAML.
  • Le nuove app C++/CX non sono supportate, anche se le app esistenti continueranno a funzionare (passa a C++ /WinRT appena possibile).
  • La distribuzione di desktop non in pacchetti non è supportata.
  • Quando si esegue un'app desktop usando F5, assicurarsi di eseguire il progetto per la creazione di pacchetti. Quando si preme F5 nel progetto dell'app viene eseguita un'app non in pacchetto, che non è ancora supportata da WinUI 3.

Funzionalità mancanti della piattaforma

  • Supporto di Xbox

  • Supporto di HoloLens

  • Popup con finestra

    • In particolare, la proprietà ShouldConstrainToRootBounds si comporta sempre come se fosse impostata su true, indipendentemente dal relativo valore.

  • Supporto per l'input penna, tra cui:

  • Acrilico di sfondo

  • MediaElement e MediaPlayerElement

  • MapControl

  • SwapChainPanel non supporta la trasparenza

  • AcrilicBrush e altri effetti che usano compositionBackdropBrush non possono eseguire l'esempio da un oggetto SwapChainPanel o WebView2.

  • Global Reveal usa il comportamento di fallback, un pennello tinta unita

  • Le isole di dati XAML non sono supportate in questa versione

  • L'uso di WinUI 3 direttamente in un'app desktop non WinUI esistente presenta la limitazione seguente: il percorso attualmente disponibile per la migrazione di un'app esistente consiste nell'aggiungere un nuovo progetto WinUI 3 alla soluzione e modificare o effettuare il refactoring della logica in base alle esigenze.

  • Application.Suspending non viene chiamato nelle app desktop. Per altri dettagli, vedere la documentazione di riferimento sulle API sull'evento Application.Suspending.

  • L'evento UISettings.ColorValuesChanged e AccessibilitySettings.HighContrastChanged non sono più supportati nelle app desktop. Questo può causare problemi se si usa per rilevare le modifiche nei temi di Windows.

  • In precedenza, per ottenere un'istanza compositionCapabilities si chiamerebbe CompositionCapabilites.GetForCurrentView(). Tuttavia, le funzionalità restituite da questa chiamata non dipendono dalla visualizzazione. Per risolvere e riflettere questo problema, è stato eliminato lo statico GetForCurrentView() in questa versione, quindi ora è possibile creare direttamente un oggetto CompositionCapabilties.

  • CoreWindow, ApplicationView, CoreApplicationView, CoreDispatcher e le relative dipendenze non sono supportate nelle app desktop (vedere di seguito)

CoreWindow, ApplicationView, CoreApplicationView e CoreDispatcher nelle app desktop

Novità di WinUI 3 Preview 4 e standard in futuro, CoreWindow ,ApplicationView, CoreApplicationViewCoreDispatchere le relative dipendenze non sono disponibili nelle app desktop. Ad esempio, la proprietà Window.Dispatcher è sempre null, ma la proprietà Window.DispatcherQueue può essere utilizzata come alternativa.

Queste API funzionano solo nelle app UWP. Nelle anteprime precedenti hanno funzionato parzialmente anche nelle app desktop, ma dall'anteprima 4 sono state completamente disabilitate. Queste API sono progettate per il caso UWP in cui è presente una sola finestra per thread e una delle funzionalità di WinUI 3 consiste nell'abilitarne di più in futuro.

Esistono API che dipendono internamente dall'esistenza di queste API, che di conseguenza non sono supportate in un'app desktop. Queste API in genere hanno un metodo statico GetForCurrentView. Ad esempio UIViewSettings.GetForCurrentView.

Per altre informazioni sulle API interessate, nonché sulle soluzioni alternative e sulle sostituzioni per queste API, vedere API di Windows Runtime non supportate nelle app desktop.

Problemi noti

  • È possibile che venga visualizzato un errore di compilazione a causa di versioni non corrispondenti di .NET SDK e winrt.runtime.dll. Come soluzione alternativa, è possibile provare quanto segue:

    Impostare in modo esplicito .NET SDK sulla versione corretta. Per determinare la versione corretta per l'app, individuare il tag <TargetFramework> nel file di progetto. Usando il numero di build di Windows SDK destinato all'app nel tag <TargetFramework> (ad esempio 18362 o 19041), aggiungere l'elemento seguente al file di progetto e quindi salvare il progetto:

    <ItemGroup>            
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.{Target Windows SDK Build Number}.16" />
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.{Target Windows SDK Build Number}.16" />
</ItemGroup>

    Si noti che questa soluzione alternativa è necessaria per .NET SDK 5.0.203 e versioni precedenti, ma non sarà necessaria per .NET SDK 5.0.204 o 5.0.300.

  • Quando si usa Visual Studio 2019 16.10 Preview 2, la struttura ad albero visuale attiva può causare un arresto anomalo. Per evitare questo problema, eseguire l'aggiornamento alla versione più recente di Visual Studio 2019 16.10 Preview.

  • I pulsanti della didascalia della finestra potrebbero non essere posizionati quando SetTitleBar non è impostato o null

Vedere la raccolta di controlli WinUI 3 (precedentemente denominata Raccolta di controlli XAML - WinUI 3 versione) per un'app di esempio che include tutti i controlli e le funzionalità che fanno parte di WinUI 3 - Project Reunion 0.8 Preview.

WinUI 3 Controls Gallery app
Esempio dell'app Raccolta di controlli WinUI 3

L'app Raccolta di controlli WinUI 3 è disponibile tramite Microsoft Store.

È anche possibile scaricare l'esempio clonando il repository GitHub. A tale scopo, clonare il ramo winui3 usando il comando seguente:

Nota

In questo repository GitHub è disponibile anche un ramo winui3preview che fornisce una versione della raccolta di controlli WinUI 3 che usa WinUI 3 - Project Reunion 0.8 Preview.

git clone --single-branch --branch winui3 https://github.com/microsoft/Xaml-Controls-Gallery.git

Dopo la clonazione, passare al ramo winui3 nell'ambiente Git locale:

git checkout winui3

Vedi anche