Freigeben über

Datumsauswahl

Mit der Datumsauswahl können Sie einen lokalisierten Datumswert mithilfe von Touch-, Maus- oder Tastatureingaben auswählen.

Beispiel für die Datumsauswahl

Ist dies das richtige Steuerelement?

Verwenden Sie eine Datumsauswahl, damit ein Benutzer ein bekanntes Datum auswählen kann, z. B. ein Geburtsdatum, bei dem der Kontext des Kalenders nicht wichtig ist.

Wenn der Kontext eines Kalenders wichtig ist, sollten Sie eine Kalenderdatumsauswahl oder Kalenderansicht verwenden.

Weitere Informationen zur Auswahl des passenden Datumssteuerelements finden Sie im Artikel Datum- und Uhrzeit-Steuerelemente.

Beispiele

Der Einstiegspunkt zeigt das ausgewählte Datum an, und wenn der Benutzer den Einstiegspunkt auswählt, wird eine Auswahloberfläche vertikal von der Mitte erweitert, damit der Benutzer eine Auswahl treffen kann. Die Datumsauswahl überlagert andere UI; Es wird keine andere Benutzeroberfläche weggeschoben.

Beispiel für die Erweiterung des Datumswählers

Erstellen einer Datumsauswahl

Öffnen Sie die WinUI 3 Gallery-App, und sehen Sie das DatePicker-Element in Aktion.

Die WinUI 3 Gallery-App enthält interaktive Beispiele für die meisten WinUI 3-Steuerelemente, -Features und -Funktionen. Abrufen der App aus dem Microsoft Store oder Abrufen des Quellcodes auf GitHub

In diesem Beispiel wird gezeigt, wie Sie eine einfache Datumsauswahl mit einer Kopfzeile erstellen.

<DatePicker x:Name="exampleDatePicker" Header="Pick a date"/>

DatePicker exampleDatePicker = new DatePicker();
exampleDatePicker.Header = "Pick a date";

Die resultierende Datumsauswahl sieht wie folgt aus:

Beispiel für die Datumsauswahl

Formatieren der Datumsauswahl

Standardmäßig zeigt die Datumsauswahl den Tag, den Monat und das Jahr an. Wenn in Ihrem Szenario für die Datumsauswahl nicht alle Felder erforderlich sind, können Sie diejenigen ausblenden, die Sie nicht benötigen. Um ein Feld auszublenden, legen Sie das entsprechende FeldVisible-Eigenschaft auf false: DayVisible, MonthVisible oder YearVisible fest.

Hier ist nur das Jahr erforderlich, daher sind die Felder „Tag“ und „Monat“ ausgeblendet.

<DatePicker x:Name="yearDatePicker" Header="In what year was Microsoft founded?" 
            MonthVisible="False" DayVisible="False"/>

Eine Datumsauswahl mit ausgeblendeten Feldern für Tag und Monat.

Der Zeichenfolgeninhalt jedes ComboBox im DatePicker wird von einem DateTimeFormatter erstellt. Sie informieren, wie Sie DateTimeFormatter den Datumswert formatieren, indem Sie eine Zeichenfolge angeben, die entweder eine Formatvorlage oder ein Formatmuster ist. Weitere Informationen finden Sie in den Eigenschaften DayFormat, MonthFormat und YearFormat .

Hier wird ein Formatmuster verwendet, um den Monat als ganze Zahl und Abkürzung anzuzeigen. Sie können dem Formatierungsmuster Literalzeichenfolgen hinzufügen, z. B. Klammern um das Monatskürzel: ({month.abbreviated}).

<DatePicker MonthFormat="{}{month.integer(2)} ({month.abbreviated})" DayVisible="False"/>

Datumsauswahl, bei der das Feld für den Tag ausgeblendet ist.

Datumswerte

Das Datumsauswahl-Steuerelement enthält sowohl Date/DateChanged- als auch SelectedDate/SelectedDateChanged-APIs. Der Unterschied zwischen diesen besteht darin, dass Date keine NULL-Werte zulässt, während SelectedDate auf NULL festgelegt werden kann.

Der Wert von SelectedDate wird verwendet, um die Datumsauswahl aufzufüllen, und lautet standardmäßig null. Wenn SelectedDate den Wert null aufweist, wird die Date-Eigenschaft auf 12/31/1600 festgelegt. Andernfalls wird der Date-Wert mit dem SelectedDate-Wert synchronisiert. Wenn SelectedDate den Wert null aufweist, ist die Auswahl „nicht festgelegt“ und zeigt die Feldnamen anstelle eines Datums an.

Ein Datumsauswahlfenster ohne ausgewähltes Datum.

Sie können die Eigenschaften MinYear und MaxYear festlegen, um die Datumswerte im Picker einzuschränken. Standardmäßig ist MinYear auf 100 Jahre vor dem aktuellen Datum und MaxYear auf 100 Jahre nach dem aktuellen Datum festgelegt.

Wenn Sie nur MinYear oder MaxYear festlegen, müssen Sie sicherstellen, dass durch das festgelegte Datum und den Standardwert des anderen Datums ein gültiger Datumsbereich gebildet wird, andernfalls ist im Auswahlfeld kein Datum zur Auswahl verfügbar. Wenn Sie beispielsweise nur yearDatePicker.MaxYear = new DateTimeOffset(new DateTime(900, 1, 1)); festlegen, wird ein ungültiger Datumsbereich mit dem Standardwert MinYear erstellt.

Initialisieren eines Datumswerts

Die Datumseigenschaften können nicht als XAML-Attributzeichenfolge festgelegt werden, da der Windows-Runtime-XAML-Parser keine Konvertierungslogik zum Konvertieren von Zeichenfolgen in Datumsangaben als DateTime / DateTimeOffset-Objekte aufweist. Hier finden Sie einige Vorschläge, wie diese Objekte im Code definiert und auf ein anderes als das aktuelle Datum festgelegt werden können.

Eine weitere mögliche Technik besteht darin, ein Datum zu definieren, das als Datenobjekt oder im Datenkontext verfügbar ist, und dann die Datumseigenschaft als XAML-Attribut festlegen, das auf eine {Binding}-Markuperweiterung verweist, die auf das Datum als Daten zugreifen kann.

Hinweis

Wichtige Informationen zu Datumswerten finden Sie im Artikel zu Datums- und Uhrzeitsteuerelementen unter "DateTime" und "Calendar" .

In diesem Beispiel wird veranschaulicht, wie die Eigenschaften SelectedDate, MinYear und MaxYear für verschiedene DatePicker-Steuerelemente festgelegt werden.

<DatePicker x:Name="yearDatePicker" MonthVisible="False" DayVisible="False"/>
<DatePicker x:Name="arrivalDatePicker" Header="Arrival date"/>

public MainPage()
{
    this.InitializeComponent();

    // Set minimum year to 1900 and maximum year to 1999.
    yearDatePicker.SelectedDate = new DateTimeOffset(new DateTime(1950, 1, 1));
    yearDatePicker.MinYear = new DateTimeOffset(new DateTime(1900, 1, 1));
    // Using a different DateTimeOffset constructor.
    yearDatePicker.MaxYear = new DateTimeOffset(1999, 12, 31, 0, 0, 0, new TimeSpan());

    // Set minimum to the current year and maximum to five years from now.
    arrivalDatePicker.MinYear = DateTimeOffset.Now;
    arrivalDatePicker.MaxYear = DateTimeOffset.Now.AddYears(5);
}

Verwenden der Datumswerte

Um den Datumswert in Ihrer App zu verwenden, verwenden Sie in der Regel eine Datenbindung an die SelectedDate-Eigenschaft oder behandeln das SelectedDateChanged-Ereignis .

Ein Beispiel für die gemeinsame Verwendung eines DatePicker und TimePicker zur Aktualisierung eines einzelnen DateTime Werts finden Sie unter Kalender-, Datums- und Uhrzeitsteuerungen – Verwenden einer Datumsauswahl und einer Zeitauswahl zusammen.

Hier verwenden Sie eine DatePicker, um einem Benutzer zu ermöglichen, sein Ankunftsdatum auszuwählen. Sie behandeln das SelectedDateChanged Ereignis, um eine DateTime-Instanz mit dem Namen arrivalDateTimezu aktualisieren.

<StackPanel>
    <DatePicker x:Name="arrivalDatePicker" Header="Arrival date"
                DayFormat="{}{day.integer} ({dayofweek.abbreviated})"
                SelectedDateChanged="arrivalDatePicker_SelectedDateChanged"/>
    <Button Content="Clear" Click="ClearDateButton_Click"/>
    <TextBlock x:Name="arrivalText" Margin="0,12"/>
</StackPanel>

public sealed partial class MainPage : Page
{
    DateTime arrivalDateTime;

    public MainPage()
    {
        this.InitializeComponent();

        // Set minimum to the current year and maximum to five years from now.
        arrivalDatePicker.MinYear = DateTimeOffset.Now;
        arrivalDatePicker.MaxYear = DateTimeOffset.Now.AddYears(5);
    }

    private void arrivalDatePicker_SelectedDateChanged(DatePicker sender, DatePickerSelectedValueChangedEventArgs args)
    {
        if (arrivalDatePicker.SelectedDate != null)
        {
            arrivalDateTime = new DateTime(args.NewDate.Value.Year, args.NewDate.Value.Month, args.NewDate.Value.Day);
        }
        arrivalText.Text = arrivalDateTime.ToString();
    }

    private void ClearDateButton_Click(object sender, RoutedEventArgs e)
    {
        arrivalDatePicker.SelectedDate = null;
        arrivalText.Text = string.Empty;
    }
}

UWP und WinUI 2

Wichtig

Die Informationen und Beispiele in diesem Artikel sind für Apps optimiert, die das Windows App SDK und WinUI 3 verwenden, gelten jedoch allgemein für UWP-Apps, die WinUI 2 verwenden. In der UWP-API-Referenz finden Sie plattformspezifische Informationen und Beispiele.

Dieser Abschnitt enthält Informationen, die Sie zum Verwenden des Steuerelements in einer UWP- oder WinUI 2-App benötigen.

APIs für dieses Steuerelement sind im Windows.UI.Xaml.Controls-Namespace vorhanden.

Wir empfehlen die Verwendung der neuesten WinUI 2 zum Abrufen der aktuellsten Stile und Vorlagen für alle Steuerelemente. WinUI 2.2 oder höher enthält eine neue Vorlage für dieses Steuerelement, die abgerundete Ecken verwendet. Weitere Informationen finden Sie unter Eckradius.