Datumsauswahl

  • Artikel

Mit der Datumsauswahl verfügen Sie über eine standardisierte Methode, Benutzern die Möglichkeit zu bieten, einen lokalisierten Datumswert per Touch-, Maus- oder Tastatureingabe auszuwählen.

Beispiel für eine Datumsauswahl

Ist dies das richtige Steuerelement?

Verwenden Sie eine Datumsauswahl, damit Benutzer ein bekanntes Datum wie etwa einen Geburtstag auswählen können, bei dem der Kalenderkontext unwichtig ist.

Wenn der Kontext eines Kalenders wichtig ist, sollten Sie die Verwendung einer Kalenderdatumsauswahl oder einer Kalenderansicht in Erwägung ziehen.

Weitere Informationen zur Auswahl des richtigen Datumssteuerelements finden Sie im Artikel über Datums- und Uhrzeitsteuerelemente.

Beispiele

Der Einstiegspunkt zeigt das ausgewählte Datum an, und wenn der Benutzer den Einstiegspunkt auswählt, wird eine Auswahloberfläche von der Bildschirmmitte aus vertikal erweitert, damit eine Auswahl getroffen werden kann. Die Datumsauswahl überlagert andere Elemente der Benutzeroberfläche; die anderen Elemente der Benutzeroberfläche werden jedoch nicht „beiseitegeschoben“.

Beispiel für die Erweiterung der Datumsauswahl

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.

Es wird empfohlen, die neueste WinUI 2-Version zu verwenden, um die aktuellsten Stile und Vorlagen für alle Steuerelemente abzurufen. 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.

Erstellen einer Datumsauswahl

Öffnen Sie die WinUI 3-Katalog-App, und sehen Sie sich den DatePicker in Aktion an.

Die WinUI 3-Katalog-App umfasst interaktive Beispiele für die meisten WinUI 3-Steuerelemente, -Features und -Funktionen. Laden Sie die App aus dem Microsoft Store herunter, oder rufen Sie den Quellcode auf GitHub ab.

Dieses Beispiel zeigt, 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 fertige Datumsauswahl sieht wie folgt aus:

Beispiel für eine 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. Wenn Sie ein Feld ausblenden möchten, legen Sie die zugehörige Visible-Eigenschaft für das Feld auf false fest: DayVisible, MonthVisible oder YearVisible.

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

Datumsauswahl, bei der die Felder „Tag“ und „Monat“ ausgeblendet sind.

Der Zeichenfolgeninhalt jedes ComboBox in der DatePicker wird von einem DateTimeFormatter erstellt. Anhand einer Zeichenfolge, die entweder eine Formatvorlage oder ein Formatmuster ist, informieren Sie DateTimeFormatter, wie der Datumswert formatiert werden soll. Weitere Informationen finden Sie in den Eigenschaften DayFormat, MonthFormat und YearFormat.

Hier wird ein Formatmuster verwendet, um den Monat als Ganzzahl 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 Steuerelement für die Datumsauswahl verfügt sowohl über die 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.

Eine Datumsauswahl ohne ausgewähltes Datum.

Sie können die Eigenschaften MinYear und MaxYear festlegen, um die Datumswerte in der Auswahl 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 nicht über eine Konvertierungslogik zum Konvertieren von Zeichenfolgen in Datumsangaben als DateTime / DateTimeOffset-Objekte verfügt. 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 andere Möglichkeit besteht darin, ein Datum zu definieren, das als Datenobjekt oder im Datenkontext verfügbar ist, und anschließend die Datumseigenschaft als XAML-Attribut festzulegen, 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-Werte.

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, nutzen Sie typischerweise eine Datenbindung an die SelectedDate-Eigenschaft oder behandeln das Ereignis SelectedDateChanged.

Ein Beispiel für die gemeinsame Verwendung von DatePicker und TimePicker zum Aktualisieren eines einzelnen DateTime-Werts finden Sie unter Kalender-, Datums- und Uhrzeitsteuerelemente – Gemeinsame Verwendung von Datumsauswahl und Zeitauswahl.

Hier verwenden Sie eine DatePicker, um einem Benutzer zu ermöglichen, sein Ankunftsdatum auszuwählen. Sie behandeln das SelectedDateChanged-Ereignis, um eine DateTime-Instanz namens arrivalDateTime zu 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;
    }
}

Beispielcode herunterladen