Freigeben über

DrawingView

  • Artikel

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 dafür ist das Bereitstellen eines Unterschriftenfelds in einer Anwendung.

Grundlegende Verwendung

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

XAML

Einbinden des XAML-Namespace

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

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

Der folgende Abschnitt:

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

Würde dann geändert werden, um xmlns einzubinden:

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

Verwenden 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 „DrawingView“-Ergebnis unter Android:

Screenshot von DrawingView unter Android

MultiLine-Verwendung

Standardmäßig unterstützt DrawingView nur 1 Linie. 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 „DrawingView“-Ergebnis unter Android:

Screenshot von DrawingView mit mehreren Zeilen unter Android

Behandeln von Ereignissen bei Abschluss der Linienzeichnung

DrawingView ermöglicht das Abonnieren von Ereignissen 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);
};

Verwenden in ScrollView

Bei Verwendung von DrawingView innerhalb von ScrollView kann die Touchinteraktion mit ScrollView unter iOS manchmal abgefangen werden. Das kann verhindert werden, indem die Eigenschaft ShouldDelayContentTouches unter iOS wie im folgenden Beispiel auf false festgelegt wird:

Ich habe dieses Problem gelöst, indem ich ios:ScrollView.ShouldDelayContentTouches="false" zum ScrollView-Objekt hinzugefügt habe, das 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-Inhaltseingaben.

Erweiterte Verwendung

Um die vollständigen Vorteile zu erhalten, stellt DrawingView die Methoden zum Abrufen des Bilddatenstroms der gezeichneten Linien bereit.

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

Eigenschaft Typ Beschreibung
Positionen ObservableCollection<IDrawingLine> Sammlung von IDrawingLine, die derzeit in der DrawingView sind
IsMultiLineModeEnabled bool Schaltet den Mehrlinienmodus um. Bei „true“ können mehrere Linien auf der DrawingView gezeichnet werden, wobei das Tippen/Klicken zwischen den Linien losgelassen wird. Hinweis: Wenn ClearOnFinish ebenfalls aktiviert ist, werden die Linien gelöscht, nachdem das Tippen/Klicken losgelassen wird. Zudem wird DrawingLineCompletedCommand nach jeder gezeichneten Linie ausgelöst.
ShouldClearOnFinish bool Gibt an, ob die DrawingView gelöscht wird, nachdem das Tippen/Klicken losgelassen wird, und eine Linie gezeichnet wird. Hinweis: Wenn IsMultiLineModeEnabled ebenfalls aktiviert ist, kann dies zu unerwartetem Verhalten führen.
DrawingLineStartedCommand ICommand Dieser Befehl wird immer aufgerufen, wenn die Zeichnung einer Linie auf der DrawingView gestartet wurde.
DrawingLineCancelledCommand ICommand Dieser Befehl wird immer aufgerufen, wenn die Zeichnung einer Linie auf der DrawingView abgebrochen wurde.
DrawingLineCompletedCommand ICommand Dieser Befehl wird immer aufgerufen, wenn die Zeichnung einer Linie auf der DrawingView abgeschlossen wurde. . Beachten Sie, dass der Befehl ausgelöst wird, nachdem das Tippen oder Klicken beendet wurde. Wenn MultiLineMode aktiviert ist, wird dieser Befehl mehrmals ausgelöst.
PointDrawnCommand ICommand Dieser Befehl wird immer aufgerufen, wenn die Zeichnung eines Punkts auf der DrawingView abgeschlossen wurde.
OnDrawingLineStarted EventHandler<DrawingLineStartedEventArgs> Das DrawingView-Ereignis tritt auf, wenn mit dem Zeichnen einer Linie begonnen wurde.
OnDrawingLineCancelled EventHandler<EventArgs> Das DrawingView-Ereignis tritt auf, wenn das Zeichnen einer Linie abgebrochen wurde.
OnDrawingLineCompleted EventHandler<DrawingLineCompletedEventArgs> Das DrawingView-Ereignis tritt auf, wenn das Zeichnen einer Linie abgeschlossen wurde.
OnPointDrawn EventHandler<PointDrawnEventArgs> Das DrawingView-Ereignis tritt auf, wenn ein Punkt gezeichnet wurde.
LineColor Color Die Farbe, die standardmäßig zum Zeichnen einer Linie auf der DrawingView verwendet wird.
LineWidth float Die Breite, die standardmäßig zum Zeichnen einer Linie auf der DrawingView verwendet wird.

DrawingLine

Die DrawingLine enthält die Liste von Punkten und ermöglicht es, jeden Linienstil individuell zu konfigurieren.

Eigenschaften

Eigenschaft Typ BESCHREIBUNG Standardwert
LineColor Color Die Farbe, die zum Zeichnen der Linie auf der DrawingView verwendet wird. Colors.Black
LineWidth float Die Breite, die zum Zeichnen der Linie auf der DrawingView verwendet wird. 5
Punkte ObservableCollection<PointF> Die Sammlung von PointF, die die Linie bildet. new()
Granularität int Die Granularität dieser Linie. Mindestwert ist 5. Je höher der Wert, desto glatter die Linie, desto langsamer das Programm. 5
ShouldSmoothPathWhenDrawn bool Aktiviert oder deaktiviert, ob diese Linie beim Zeichnen geglättet wird (Antialiasing). false

Benutzerdefinierte IDrawingLine

Es gibt zwei Schritte, um die standardmäßige DrawingLine durch die benutzerdefinierte Implementierung zu ersetzen:

  1. Erstellen Sie eine benutzerdefinierte Klasse, die IDrawingLine implementiert: 
    public class MyDrawingLine : IDrawingLine
{
    public ObservableCollection<PointF> Points { get; } = new();
    ...
}
  2. Erstellen Sie eine benutzerdefinierte Klasse, die IDrawingLineAdapter implementiert. 
    public class MyDrawingLineAdapter : IDrawingLineAdapter
{
    public IDrawingLine(MauiDrawingLine mauiDrawingLine)
    {
        return new MyDrawingLine
        {
            Points = mauiDrawingLine.Points,
            ...
        }
    }
}
  3. Legen Sie einen benutzerdefinierten IDrawingLineAdapter im IDrawingViewHandler fest: 
    var myDrawingLineAdapter = new MyDrawingLineAdapter();
drawingViewHandler.SetDrawingLineAdapter(myDrawingLineAdapter);

DrawingLineStartedEventArgs

Ereignisargument, das den letzten gezeichneten Punkt enthält.

Eigenschaften

Eigenschaft Typ Beschreibung
Point PointF Letzter gezeichneter Punkt.

DrawingLineCompletedEventArgs

Ereignisargument, das die letzte gezeichnete Linie enthält.

Eigenschaften

Eigenschaft Typ Beschreibung
LastDrawingLine IDrawingLine Letzte gezeichnete Linie.

PointDrawnEventArgs

Ereignisargument, das den letzten gezeichneten Punkt enthält.

Eigenschaften

Eigenschaft Typ Beschreibung
Point PointF Letzter gezeichneter Punkt.

Methoden

Methode Beschreibung
GetImageStream Ruft einen Stream ab, der ein Bild der Lines enthält, die derzeit auf der DrawingView gezeichnet werden.
GetImageStream (static) Ruft einen Stream ab, der ein Bild der Sammlung von IDrawingLine enthält, die als Parameter bereitgestellt wird.

Beispiele

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

API

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