Freigeben über


Zeichnungsansicht

Die DrawingView bietet eine Oberfläche, die das Zeichnen von Linien über die Verwendung von Touch- oder Mausinteraktionen ermöglicht. Das Ergebnis einer Benutzerzeichnung kann als Bild gespeichert werden. Ein gängiger Anwendungsfall hierfür ist das Bereitstellen eines Signaturfelds in einer Anwendung.

Grundlegende Nutzung

DrawingView ermöglicht das Festlegen von Linienfarbe, Linienbreite und Bindung an die Auflistung von Linien.

XAML

Einschließen des XAML-Namespaces

Um das Toolkit in XAML verwenden zu können, muss die folgende xmlns zu Ihrer Seite oder Ansicht hinzugefügt werden:

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

Daher folgt Folgendes:

<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>

Es würde wie folgt geändert werden, um die xmlns einzuschließen:

<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>

Verwendung von 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
};

Der folgende Screenshot zeigt das resultierende DrawingView unter Android:

Screenshot einer DrawingView unter Android

MultiLine-Verwendung

Standardmäßig unterstützt DrawingView nur 1 Zeile. Um MultiLine zu aktivieren, legen Sie IsMultiLineModeEnabled auf "true" fest. Stellen Sie sicher, dass ShouldClearOnFinish "false" ist.

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,
};

Der folgende Screenshot zeigt das resultierende DrawingView unter Android:

Screenshot einer DrawingView mit mehrzeiligen Abschnitten auf Android

Speichern des Ergebnisses in einem Bild

Das .NET MAUI Community Toolkit bietet mehrere Optionen zum Speichern der resultierenden Zeichnung in einem Bild, diese Optionen sind wie folgt:

Speichern aus dem DrawingView

Die DrawingView stellt die GetImageStream-Methode bereit, die ein Bild generiert und den Inhalt in einem Streamzurückgibt.

Im folgenden Beispiel wird die Zeichnung in ein Bild mit einer gewünschten Breite von 400 und einer gewünschten Höhe von 300 exportiert. Die gewünschten Abmessungen werden angepasst, um sicherzustellen, dass das Seitenverhältnis der Zeichnung beibehalten wird.

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

Anmerkung

Standardmäßig gibt die GetImageStream-Methode ein Bild zurück, das die gezeichneten Linien enthält. Dies entspricht nicht der vollständigen Oberfläche, die der Benutzer sieht. Um ein Bild zu generieren, das direkt mit der in der Anwendung angezeigten Oberfläche übereinstimmt, muss die GetImageStream-Methode mit dem parameter DrawingViewOutputOption verwendet werden.

Das folgende Beispiel zeigt, wie Sie ein Bild generieren, das direkt mit der DrawingView-Oberfläche übereinstimmt, die in einer Anwendung angezeigt wird:

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

Speichern aus dem DrawingViewService

Die Verwendung der DrawingView-Methoden kann es schwierig machen, eine Anwendung mit dem MVVM-Muster zu erstellen, um dies zu bewältigen, bietet das .NET MAUI Community Toolkit auch die DrawingViewService Klasse, die auch die Möglichkeit zum Generieren eines Bildstreams ermöglicht.

ImageLineOptions.JustLines

Das folgende Beispiel zeigt, wie Sie einen Bildstrom mit einer gewünschten Breite von 1920 und höhe von 1080 und einem blauen Hintergrund generieren. Entwickler können die ImageLineOptions.JustLines-Methode verwenden, um geeignete Optionen bereitzustellen, um nur die gezeichneten Linien zu exportieren. Informationen zum Exportieren des gesamten Zeichenbereichs finden Sie unter ImageLineOptions.FullCanvas

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

ImageLineOptions.FullCanvas

Um ein Bild zu generieren, das direkt mit der DrawingView-Oberfläche übereinstimmt, kann die ImageLineOptions.FullCanvas-Methode wie folgt verwendet werden.

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

Für dieses Beispiel wurden die Eigenschaften CanvasWidth und CanvasHeight an die Daten der Eigenschaften Width und Height der DrawingView gebunden. Die vollständige Lösung finden Sie in der .NET MAUI Community Toolkit Sample Application.

Behandeln eines Ereignisses beim Abschluss der Zeichnungslinie

DrawingView ermöglicht das Abonnieren der Ereignisse wie OnDrawingLineCompleted. Der entsprechende Befehl DrawingLineCompletedCommand ist ebenfalls verfügbar.

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);
};

Verwendung in einer ScrollView

Bei Verwendung der DrawingView in einem ScrollView kann die Touchinteraktion mit dem ScrollView manchmal auf iOS abgefangen werden. Dies kann verhindert werden, indem die ShouldDelayContentTouches-Eigenschaft gemäß dem folgenden Beispiel auf iOS auf false festgelegt wird:

Ich habe dieses Problem gelöst, indem ich ios:ScrollView.ShouldDelayContentTouches="false" zum ScrollView-Objekt hinzufügte, das die DrawingView enthält.

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

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

        <DrawingView />

    </ScrollView>

</ContentPage>

Weitere Informationen finden Sie unter ScrollView-Inhaltsberührungen.

Erweiterte Verwendung

Um den vollen Nutzen zu ziehen, bietet das DrawingView Methoden zum Abrufen des Bildstroms der Zeichnungslinien.

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);

Eigenschaften

Eigentum Art Beschreibung
Linien ObservableCollection<IDrawingLine> Sammlung von IDrawingLine, die sich momentan auf dem DrawingView befinden
IsMultiLineModeEnabled bool Schaltet den mehrzeiligen Modus um. Wenn 'true' gesetzt ist, können mehrere Linien auf der DrawingView gezeichnet werden, während zwischen den Linien das Tippen/Klicken losgelassen wird. Hinweis: Wenn ClearOnFinish ebenfalls aktiviert ist, werden die Zeilen gelöscht, nachdem das Tippen/Klicken losgelassen wurde. Darüber hinaus wird DrawingLineCompletedCommand nach jeder gezeichneten Linie ausgelöst.
SollBeimAbschlussLöschen bool Gibt an, ob die DrawingView nach dem Loslassen des Tippens/Klickens gelöscht wird und eine Linie gezeichnet wird. Hinweis: Wenn IsMultiLineModeEnabled ebenfalls aktiviert ist, kann dies zu unerwartetem Verhalten führen.
BefehlZeichnungsLinieGestartet ICommand Dieser Befehl wird immer aufgerufen, wenn die Zeichnung einer Zeile auf dem DrawingView gestartet wurde.
ZeichenLinieAbgebrochenBefehl ICommand Dieser Befehl wird immer aufgerufen, wenn die Zeichnung einer Zeile auf dem DrawingView abgebrochen wurde.
ZeichenlinienAbschlussBefehl ICommand Dieser Befehl wird immer aufgerufen, wenn die Zeichnung einer Zeile auf dem DrawingView abgeschlossen ist. . Beachten Sie, dass dies ausgelöst wird, nachdem das Tippen oder Klicken aufgehoben wurde. Wenn MultiLineMode aktiviert ist, wird dieser Befehl mehrmals ausgelöst.
PointDrawnCommand ICommand Dieser Befehl wird immer aufgerufen, wenn die Zeichnung eines Punkts auf dem DrawingView abgeschlossen ist.
OnDrawingLineStarted EventHandler<DrawingLineStartedEventArgs> DrawingView Ereignis tritt auf, wenn das Zeichnen der Linie beginnt.
OnDrawingLineCancelled EventHandler<EventArgs> DrawingView-Ereignis tritt auf, wenn das Zeichnen einer Linie abgebrochen wird.
OnDrawingLineCompleted EventHandler<DrawingLineCompletedEventArgs> DrawingView Ereignis tritt auf, wenn das Zeichnen einer Linie abgeschlossen ist.
OnPointDrawn EventHandler<PointDrawnEventArgs> DrawingView Ereignis tritt ein, wenn ein Punkt gezeichnet wird.
LineColor Color Die Farbe, die standardmäßig zum Zeichnen einer Linie auf der DrawingViewverwendet wird.
Linienstärke float Die Breite, die standardmäßig zum Zeichnen einer Linie auf dem DrawingViewverwendet wird.

DrawingLine

Die DrawingLine enthält die Liste der Punkte und ermöglicht die Konfiguration der einzelnen Linienstile.

Eigenschaften

Eigentum Typ Beschreibung Standardwert
LineColor Color Die Farbe, die zum Zeichnen der Linie auf der DrawingViewverwendet wird. Colors.Black
Linienbreite float Die Breite, die verwendet wird, um die Linie auf dem DrawingViewzu zeichnen. 5
Punkte ObservableCollection<PointF> Die Sammlungselemente von PointF, die die Linie bilden. new()
Körnigkeit int Die Granularität dieser Zeile. Der Min.-Wert ist 5. Je höher der Wert, desto glatter die Linie, desto langsamer das Programm. 5
Sollte den Pfad beim Zeichnen glätten bool Aktiviert oder deaktiviert, ob diese Linie geglättet (antialiasiert) wird, wenn sie gezeichnet wird. false

Custom IDrawingLine

Es gibt zwei Schritte, um die Standard-DrawingLine durch die benutzerdefinierte Implementierung zu ersetzen:

  1. Erstellen Sie benutzerdefinierte Klasse, die IDrawingLineimplementiert:
    public class MyDrawingLine : IDrawingLine
    {
        public ObservableCollection<PointF> Points { get; } = new();
        ...
    }
    
  2. Erstellen Sie benutzerdefinierte Klasse, die IDrawingLineAdapterimplementiert.
    public class MyDrawingLineAdapter : IDrawingLineAdapter
    {
        public IDrawingLine(MauiDrawingLine mauiDrawingLine)
        {
            return new MyDrawingLine
            {
                Points = mauiDrawingLine.Points,
                ...
            }
        }
    }
    
  3. Benutzerdefinierte IDrawingLineAdapter in IDrawingViewHandlerfestlegen:
    var myDrawingLineAdapter = new MyDrawingLineAdapter();
    drawingViewHandler.SetDrawingLineAdapter(myDrawingLineAdapter);
    

ZeichenLinienGestartetEreignisArgumente

Ereignisargument, das den letzten Zeichnungspunkt enthält.

Eigenschaften

Eigentum Typ Beschreibung
Punkt PointF Letzter Zeichnungspunkt.

DrawingLineCompletedEventArgs

Ereignisargument, das die letzte Zeichnungslinie enthält.

Eigenschaften

Eigentum Art Beschreibung
LastDrawingLine IDrawingLine Letzte Zeichnungslinie.

PointDrawnEventArgs

Ereignisargument, das den letzten Zeichnungspunkt enthält.

Eigenschaften

Eigentum Art Beschreibung
Punkt PointF Letzter Zeichnungspunkt.

Methodik

Methode Beschreibung
GetImageStream Ruft ein Stream ab, das ein Bild des Lines enthält, das derzeit auf dem DrawingViewgezeichnet wird.
GetImageStream (statisch) Ruft eine Stream ab, die ein Bild der Auflistung von IDrawingLine enthält, die als Parameter bereitgestellt wird.

Beispiele

Sie finden ein Beispiel für dieses Feature in Aktion in der .NET MAUI Community Toolkit Sample Application.

API

Sie finden den Quellcode für DrawingView über das .NET MAUI Community Toolkit GitHub Repository.