Condividi tramite

DrawingView

Il DrawingView fornisce una superficie che consente il disegno di linee attraverso l'uso dell'interazione tramite tocco o mouse. Il risultato di un disegno degli utenti può essere salvato come immagine. Un caso d'uso comune consiste nel fornire una casella di firma in un'applicazione.

Utilizzo di base

DrawingView consente di impostare il colore della linea, la larghezza della linea e l'associazione alla raccolta di linee.

XAML

Inclusione del namespace XAML

Per usare il toolkit in XAML, è necessario aggiungere il seguente xmlns nella pagina o nella visualizzazione.

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Di conseguenza:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Verrà modificato in modo da includere il xmlns come indicato di seguito:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Uso di DrawingView

<toolkit:DrawingView
            Lines="{Binding MyLines}"
            LineColor="Red"
            LineWidth="5" />

C#

using CommunityToolkit.Maui.Views;

var drawingView = new DrawingView
{
    Lines = new ObservableCollection<IDrawingLine>(),
    LineColor = Colors.Red,
    LineWidth = 5
};

Lo screenshot seguente mostra l'oggetto DrawingView risultante in Android:

Screenshot di DrawingView su Android

Utilizzo multilinea

Per impostazione predefinita, DrawingView supporta solo 1 riga. Per abilitare MultiLine, impostare IsMultiLineModeEnabled su vero. Assicurarsi che ShouldClearOnFinish sia falso.

XAML

<views:DrawingView
            Lines="{Binding MyLines}"
            IsMultiLineModeEnabled="true"
            ShouldClearOnFinish="false" />

C#

using CommunityToolkit.Maui.Views;

var gestureImage = new Image();
var drawingView = new DrawingView
{
    Lines = new ObservableCollection<IDrawingLine>(),
    IsMultiLineModeEnabled = true,
    ShouldClearOnFinish = false,
};

Lo screenshot seguente mostra l'oggetto DrawingView risultante su dispositivo Android.

Screenshot di DrawingView con più righe su Android

Salvataggio del risultato in un'immagine

.NET MAUI Community Toolkit offre diverse opzioni per salvare il disegno risultante in un'immagine, queste opzioni sono le seguenti:

Salvataggio dalla DrawingView

Il DrawingView fornisce il metodo GetImageStream che genererà un'immagine e restituirà il contenuto in un Stream.

Nell'esempio seguente il disegno verrà esportato in un'immagine con una larghezza desiderata di 400 e un'altezza desiderata di 300. Le dimensioni desiderate verranno modificate per assicurarsi che il rapporto di aspetto del disegno sia conservato.

await drawingView.GetImageStream(desiredWidth: 400, desiredHeight: 300);

Nota

Per impostazione predefinita, il metodo GetImageStream restituirà un'immagine contenente le linee disegnate, che non corrisponderà alla superficie completa visualizzata dall'utente. Per generare un'immagine che corrisponde direttamente alla superficie visualizzata nell'applicazione, è necessario usare il metodo GetImageStream con il parametro DrawingViewOutputOption.

L'esempio seguente illustra come generare un'immagine che corrisponde direttamente alla superficie DrawingView visualizzata in un'applicazione:

await drawingView.GetImageStream(desiredWidth: 400, desiredHeight: 300, imageOutputOption: DrawingViewOutputOption.FullCanvas);

Salvataggio dalla DrawingViewService

L'uso dei metodi di DrawingView può rendere difficile creare un'applicazione usando il modello MVVM, per facilitare questa gestione di .NET MAUI Community Toolkit fornisce anche la classe DrawingViewService che consentirà anche di generare un flusso di immagini.

ImageLineOptions.JustLines

L'esempio seguente mostra come generare un flusso di immagini di una larghezza desiderata di 1920 e altezza di 1080 e uno sfondo blu. Gli sviluppatori possono usare il metodo ImageLineOptions.JustLines per fornire opzioni appropriate per esportare solo le linee disegnate. Per esportare l'intera area di disegno, vedere ImageLineOptions.FullCanvas

await using var stream = await DrawingViewService.GetImageStream(
    ImageLineOptions.JustLines(Lines, new Size(1920, 1080), Brush.Blue));

ImageLineOptions.FullCanvas

Per generare un'immagine che corrisponde direttamente all'area DrawingView, è possibile usare il metodo ImageLineOptions.FullCanvas come indicato di seguito.

await using var stream = await DrawingViewService.GetImageStream(
    ImageLineOptions.FullCanvas(Lines, new Size(1920, 1080), Brush.Blue, new Size(CanvasWidth, CanvasHeight)));

Ai fini di questo esempio, le proprietà CanvasWidth e CanvasHeight sono stati associati rispettivamente alle proprietà Width e Height del DrawingView. Per la soluzione completa, vedere .NET MAUI Community Toolkit Sample Application.

Gestire l'evento quando il disegno della linea è completato

DrawingView consente di sottoscrivere gli eventi come OnDrawingLineCompleted. È disponibile anche il comando corrispondente DrawingLineCompletedCommand.

XAML

<views:DrawingView
            Lines="{Binding MyLines}"
            DrawingLineCompletedCommand="{Binding DrawingLineCompletedCommand}"
            OnDrawingLineCompleted="OnDrawingLineCompletedEvent" />

C#

using CommunityToolkit.Maui.Views;

var gestureImage = new Image();
var drawingView = new DrawingView
{
    Lines = new ObservableCollection<IDrawingLine>(),
    DrawingLineCompletedCommand = new Command<IDrawingLine>(async (line) =>
    {
        var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

        var stream = await line.GetImageStream(gestureImage.Width, gestureImage.Height, Colors.Gray.AsPaint(), cts.Token);
        gestureImage.Source = ImageSource.FromStream(() => stream);
    })
};
drawingView.OnDrawingLineCompleted += async (s, e) =>
{
    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

    var stream = await e.LastDrawingLine.GetImageStream(gestureImage.Width, gestureImage.Height, Colors.Gray.AsPaint(), cts.Token);
    gestureImage.Source = ImageSource.FromStream(() => stream);
};

Usare all'interno di un controllo ScrollView

Quando si usa il DrawingView all'interno di un ScrollView l'interazione tramite tocco con il ScrollView può talvolta essere intercettata in iOS. Ciò può essere impedito impostando la proprietà ShouldDelayContentTouches su false in iOS in base all'esempio seguente:

Ho risolto questo problema aggiungendo ios:ScrollView.ShouldDelayContentTouches="false" a ScrollView che contiene DrawingView:

<ContentPage
    xmlns:ios="clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;assembly=Microsoft.Maui.Controls">

    <ScrollView ios:ScrollView.ShouldDelayContentTouches="false">

        <DrawingView />

    </ScrollView>

</ContentPage>

Per ulteriori informazioni, fare riferimento a Tocchi sul contenuto di ScrollView.

Utilizzo avanzato

Per ottenere tutti i vantaggi, il DrawingView fornisce i metodi per ottenere lo stream di immagini delle linee tracciate.

XAML

<toolkit:DrawingView
            x:Name="DrawingViewControl"
            Lines="{Binding MyLines}"
            IsMultiLineModeEnabled="true"
            ShouldClearOnFinish="true"
            DrawingLineCompletedCommand="{Binding DrawingLineCompletedCommand}"
            OnDrawingLineCompleted="OnDrawingLineCompletedEvent"
            LineColor="Red"
            LineWidth="5"
            HorizontalOptions="Fill"
            VerticalOptions="Fill">
            <toolkit:DrawingView.Background>
                    <LinearGradientBrush StartPoint="0,0"
                                         EndPoint="0,1">
                        <GradientStop Color="Blue"
                                      Offset="0"/>
                        <GradientStop Color="Yellow"
                                      Offset="1"/>
                    </LinearGradientBrush>
            </toolkit:DrawingView.Background>
</toolkit:DrawingView>

C#

using CommunityToolkit.Maui.Views;

var gestureImage = new Image();
var drawingView = new DrawingView
{
    Lines = new ObservableCollection<IDrawingLine>(),
    IsMultiLineModeEnabled = true,
    ShouldClearOnFinish = false,
    DrawingLineCompletedCommand = new Command<IDrawingLine>(async (line) =>
    {
        var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

        var stream = await line.GetImageStream(gestureImage.Width, gestureImage.Height, Colors.Gray.AsPaint(), cts.Token);
        gestureImage.Source = ImageSource.FromStream(() => stream);
    }),
    LineColor = Colors.Red,
    LineWidth = 5,
    Background = Brush.Red
};
drawingView.OnDrawingLineCompleted += async (s, e) =>
{
    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

    var stream = await e.LastDrawingLine.GetImageStream(gestureImage.Width, gestureImage.Height, Colors.Gray.AsPaint(), cts.Token);
    gestureImage.Source = ImageSource.FromStream(() => stream);
};

// get stream from lines collection
var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var lines = new List<IDrawingLine>();
var stream1 = await DrawingView.GetImageStream(
                lines,
                new Size(gestureImage.Width, gestureImage.Height),
                Colors.Black.
                cts.Token);

// get steam from the current DrawingView
var stream2 = await drawingView.GetImageStream(gestureImage.Width, gestureImage.Height, cts.Token);

Proprietà

Proprietà Digitare Descrizione
Poema ObservableCollection<IDrawingLine> Raccolta di IDrawingLine attualmente presenti nel DrawingView
ModalitàMultiLineaAbilitata bool Attiva/disattiva la modalità a più righe. Quando vero, è possibile disegnare più linee sulla DrawingView mentre il tocco/clic viene rilasciato fra una linea e l'altra. Nota: quando anche ClearOnFinish è abilitato, le linee vengono cancellate dopo il rilascio del tocco o del clic. Inoltre, DrawingLineCompletedCommand verrà attivato dopo ogni linea disegnata.
DovrebbeCancellareAlTermine bool Indica se il DrawingView viene cancellato dopo il rilascio del tocco o del clic e viene disegnata una linea. Nota: quando anche IsMultiLineModeEnabled è abilitato, questo potrebbe causare un comportamento imprevisto.
ComandoInizioDisegnoLinea ICommand Questo comando viene richiamato ogni volta che il disegno di una riga sul DrawingView è stato avviato.
ComandoDisegnoLineaAnnullato ICommand Questo comando viene richiamato ogni volta che il disegno di una riga sul DrawingView è stato annullato.
ComandoDisegnoLineaCompletata ICommand Questo comando viene richiamato ogni volta che il disegno di una riga sul DrawingView è stato completato. . Si noti che questo viene attivato dopo che il tocco o il clic è stato sollevato. Quando MultiLineMode è abilitato, questo comando viene attivato più volte.
PointDrawnCommand ICommand Questo comando viene richiamato ogni volta che il disegno di un punto sul DrawingView è stato completato.
InizioDisegnoLinea EventHandler<DrawingLineStartedEventArgs> L'evento DrawingView si verifica quando si inizia a tracciare una linea.
SuLineaDisegnoAnnullata EventHandler<EventArgs> DrawingView evento si verifica quando la linea di disegno viene annullata.
Al Completamento del Disegno della Linea EventHandler<DrawingLineCompletedEventArgs> DrawingView l'evento si verifica quando il disegno della linea è completato.
OnPointDrawn EventHandler<PointDrawnEventArgs> L'evento DrawingView si verifica quando viene disegnato il punto.
Colore della Linea Color Colore utilizzato per impostazione predefinita per disegnare una linea sul DrawingView.
Larghezza Linea float Larghezza utilizzata per impostazione predefinita per disegnare una linea sul DrawingView.

DrawingLine

Il DrawingLine contiene l'elenco di punti e consente di configurare singolarmente ogni stile di linea.

Proprietà

Proprietà Digitare Descrizione Valore predefinito
LineColor Color Colore utilizzato per disegnare la linea sul DrawingView. Colors.Black
LarghezzaLinea float Larghezza utilizzata per disegnare la linea sul DrawingView. 5
Punti ObservableCollection<PointF> Raccolta di PointF che costituisce la linea. new()
Granularità int Granularità di questa riga. Il valore minimo è 5. Maggiore è il valore, più liscia è la linea, più lento è il programma. 5
DovrebbeLisciareIlPercorsoQuandoDisegnato bool Abilita o disabilita lo smussamento (anti-aliasing) di questa linea quando viene disegnata. false

IDrawingLine personalizzato

Esistono 2 passaggi per sostituire il DrawingLine predefinito con l'implementazione personalizzata:

  1. Creare una classe personalizzata che implementa IDrawingLine: 
    public class MyDrawingLine : IDrawingLine
{
    public ObservableCollection<PointF> Points { get; } = new();
    ...
}
  2. Creare una classe personalizzata che implementa IDrawingLineAdapter. 
    public class MyDrawingLineAdapter : IDrawingLineAdapter
{
    public IDrawingLine(MauiDrawingLine mauiDrawingLine)
    {
        return new MyDrawingLine
        {
            Points = mauiDrawingLine.Points,
            ...
        }
    }
}
  3. Impostare IDrawingLineAdapter personalizzate in IDrawingViewHandler: 
    var myDrawingLineAdapter = new MyDrawingLineAdapter();
drawingViewHandler.SetDrawingLineAdapter(myDrawingLineAdapter);

DrawingLineStartedEventArgs

Argomento dell'evento che contiene l'ultimo punto di disegno.

Proprietà

Proprietà Digitare Descrizione
Punto PointF Ultimo punto di disegno.

DrawingLineCompletedEventArgs

Argomento dell'evento che contiene l'ultima linea di disegno.

Proprietà

Proprietà Digitare Descrizione
LastDrawingLine IDrawingLine Ultima linea di disegno.

PointDrawnEventArgs

Argomento dell'evento che contiene l'ultimo punto di disegno.

Proprietà

Proprietà Digitare Descrizione
Punto PointF Ultimo punto di disegno.

Metodi

Metodo Descrizione
GetImageStream Recupera un Stream contenente un'immagine dei Lines attualmente disegnati sul DrawingView.
GetImageStream (statico) Recupera un Stream contenente un'immagine della raccolta di IDrawingLine fornita come parametro.

Esempi

È possibile trovare un esempio di questa funzionalità in azione nell'applicazione di esempio .NET MAUI Community Toolkit .

Interfaccia di Programmazione delle Applicazioni (API)

È possibile trovare il codice sorgente per DrawingView nel repository GitHub .NET MAUI Community Toolkit.

  • Last updated on