Управления элементов диалога
Диалоговые окна — это модальные наложения пользовательского интерфейса, которые предоставляют контекстную информацию о приложении. Они блокируют взаимодействие с окном приложения, пока пользователь явно их не закроет. Они часто запрашивают от пользователя какое-то действие.
Это правильный элемент управления?
Диалоговые окна используются для уведомления пользователей о важной информации или запроса подтверждения либо дополнительных сведений перед совершением действия.
Рекомендации по целесообразности использования диалоговых окон и всплывающих элементов (аналогичных элементов управления) приведены в разделе Диалоговые окна и всплывающие элементы.
Общие рекомендации
- Четко определите проблему или цель пользователя в первой строке текста диалогового окна.
- Заголовок диалогового окна является основной инструкцией и является необязательным.
- Используйте короткое название, чтобы объяснить, что нужно делать с диалогом.
- Если вы используете диалоговое окно для доставки простого сообщения, ошибки или вопроса, вы также можете опустить заголовок. Опирайтесь на текст содержимого, чтобы доставить эти основные сведения.
- Убедитесь, что заголовок относится непосредственно к выбору кнопки.
- Содержимое диалогового окна содержит описательный текст и является обязательным.
- Как можно проще представить сообщение, ошибку или блокировать вопрос.
- Если используется название диалогового окна, используйте область содержимого для получения дополнительных сведений или определения терминологии. Не повторяйте название, изменяя формулировку.
- Должна появиться по крайней мере одна кнопка диалогового окна.
- Убедитесь, что диалоговое окно имеет по крайней мере одну кнопку, соответствующую безопасному и обратимому действию, например "Понял", "Закрыть" или "Отмена". Используйте API CloseButton, чтобы добавить эту кнопку.
- В качестве текста кнопки используйте конкретные варианты ответа на основную инструкцию или содержимое. Примером является вопрос: "Хотите разрешить приложению AppName доступ к вашему местоположению?", а затем кнопки «Разрешить» и «Блокировать». Конкретные ответы можно понять быстрее, что приводит к эффективному принятию решений.
- Убедитесь, что текст кнопки действия является кратким. Короткие строки позволяют пользователю сделать выбор быстро и уверенно.
- В дополнение к безопасному, недеструктивному действию можно по желанию представить пользователю одну или две кнопки действий, связанные с основной инструкцией. Эти кнопки действия "выполнить" подтверждают главную цель диалогового окна. Используйте API SecondaryButton и PrimaryButton для добавления этих действий "выполнить".
- Кнопки действий "выполнить" должны отображаться как крайние левые кнопки. Безопасное неразрушающее действие должно быть представлено самой правой кнопкой.
- При необходимости можно выделить одну из трех кнопок в качестве кнопки диалогового окна по умолчанию. Используйте API DefaultButton для выделения одной из кнопок.
- Не используйте диалоговые окна для ошибок, которые являются контекстными для определенного места на странице, например ошибки проверки (например, в полях паролей), используйте холст приложения для отображения встроенных ошибок.
- Используйте класс ContentDialog для создания элементов диалогового окна. Не используйте устаревший API MessageDialog.
Создание диалогового окна
- Важные API: класс ContentDialog
Приложение WinUI 3 Gallery включает интерактивные примеры большинства элементов управления и функций WinUI 3. Получение приложения из Microsoft Store или получение исходного кода на GitHub
Чтобы создать диалоговое окно, используйте класс ContentDialog. Диалоговое окно можно создать в коде или разметке. Хотя обычно проще определять элементы пользовательского интерфейса в XAML, в случае простого диалога проще просто использовать код. В этом примере создается диалоговое окно для уведомления пользователя о отсутствии подключения WiFi, а затем используется метод ShowAsync для отображения.
private async void DisplayNoWifiDialog()
{
ContentDialog noWifiDialog = new ContentDialog
{
Title = "No wifi connection",
Content = "Check your connection and try again.",
CloseButtonText = "OK"
};
ContentDialogResult result = await noWifiDialog.ShowAsync();
}
Когда пользователь нажимает кнопку диалогового окна, метод ShowAsync возвращает ContentDialogResult, чтобы вы могли узнать, какую кнопку нажал пользователь.
Диалоговое окно в этом примере задает вопрос и использует возвращенный ContentDialogResult для определения ответа пользователя.
private async void DisplayDeleteFileDialog()
{
ContentDialog deleteFileDialog = new ContentDialog
{
Title = "Delete file permanently?",
Content = "If you delete this file, you won't be able to recover it. Do you want to delete it?",
PrimaryButtonText = "Delete",
CloseButtonText = "Cancel"
};
ContentDialogResult result = await deleteFileDialog.ShowAsync();
// Delete the file if the user clicked the primary button.
/// Otherwise, do nothing.
if (result == ContentDialogResult.Primary)
{
// Delete the file.
}
else
{
// The user clicked the CloseButton, pressed ESC, Gamepad B, or the system back button.
// Do nothing.
}
}
Обеспечить безопасное действие
Так как диалоговые окна блокируют взаимодействие с пользователем, а кнопки — это основной механизм, позволяющий пользователям закрыть диалоговое окно, убедитесь, что диалоговое окно содержит по крайней мере одну недеструктивную и безопасную кнопку, например "Закрыть" или "Понятно". Все диалоговые окна должны содержать по крайней мере одну кнопку безопасного действия, позволяющую закрыть диалоговое окно. Это гарантирует, что пользователь сможет спокойно закрыть диалоговое окно без выполнения какого-либо действия.
private async void DisplayNoWifiDialog()
{
ContentDialog noWifiDialog = new ContentDialog
{
Title = "No wifi connection",
Content = "Check your connection and try again.",
CloseButtonText = "OK"
};
ContentDialogResult result = await noWifiDialog.ShowAsync();
}
Когда диалоговые окна используются для отображения блокирующего вопроса, диалоговое окно должно содержать кнопки действий, связанные с этим вопросом. Кнопка "безопасного и недеструктивного" действия может сопровождаться одной или двумя кнопками действия "выполнить". Предлагая пользователю несколько вариантов на выбор, убедитесь, что кнопки точно соответствуют действиям "выполнить" и безопасным действиям "не выполнять", связанным с предложенным вопросом.
private async void DisplayLocationPromptDialog()
{
ContentDialog locationPromptDialog = new ContentDialog
{
Title = "Allow AppName to access your location?",
Content = "AppName uses this information to help you find places, connect with friends, and more.",
CloseButtonText = "Block",
PrimaryButtonText = "Allow"
};
ContentDialogResult result = await locationPromptDialog.ShowAsync();
}
Диалоговые окна с тремя кнопками используются, когда вы предлагаете пользователю два действия "выполнить" и одно действие "не выполнять". Диалоговые окна с тремя кнопками следует использовать не слишком часто. В них должны четко различаться дополнительное действие и безопасное действие (закрытие).
private async void DisplaySubscribeDialog()
{
ContentDialog subscribeDialog = new ContentDialog
{
Title = "Subscribe to App Service?",
Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
CloseButtonText = "Not Now",
PrimaryButtonText = "Subscribe",
SecondaryButtonText = "Try it"
};
ContentDialogResult result = await subscribeDialog.ShowAsync();
}
Три кнопки в диалоговом окне
ContentDialog поддерживает три типа кнопки, которые можно использовать для создания диалоговых окон.
- CloseButton (обязательный) представляет безопасное, обратимое действие, которое позволяет пользователю закрыть диалоговое окно. Отображается в виде правой кнопки.
- PrimaryButton - Необязательный - представляет первое действие «выполнить». Отображается в виде левой кнопки.
- SecondaryButton - Опционально - представляет второе действие "выполнить". Отображается в виде средней кнопки.
Использование встроенных кнопок позволяет их правильно разместить в окне, а также гарантирует, что они будут правильно реагировать на события клавиатуры, что область команд останется видимой, даже когда отображена экранная клавиатура, и что диалоговое окно будет выглядеть согласованно с другими диалоговыми окнами.
Кнопка закрытия
Каждое диалоговое окно должно содержать кнопку безопасного и недеструктивного действия, которая позволяет пользователям уверенно закрыть диалоговое окно.
Используйте API ContentDialog.CloseButton для создания этой кнопки. Это позволит обеспечить правильное взаимодействие с пользователем для всех методов ввода, включая мышь, клавиатуру, сенсорный ввод и игровой контроллер. Это взаимодействие будет происходить в следующих случаях:
- Пользователь щелкает или нажимает кнопку CloseButton.
- Пользователь нажимает системную кнопку "Назад".
- Пользователь нажимает кнопку ESC на клавиатуре.
- Пользователь нажимает Gamepad B.
Когда пользователь нажимает кнопку диалогового окна, метод ShowAsync возвращает ContentDialogResult, чтобы вы могли узнать, какую кнопку нажал пользователь. При нажатии кнопки закрытия возвращается ContentDialogResult.None.
Основная кнопка и Второстепенная кнопка
Помимо CloseButton, вы можете также предоставить пользователю одну или две кнопки действия, связанные с основной инструкцией. Используйте PrimaryButton для первого действия "выполнить" и SecondaryButton — для второго действия "выполнить". В диалоговых окнах с тремя кнопками PrimaryButton обычно обозначает утвердительное действие "выполнить", тогда как SecondaryButton обычно обозначает нейтральное или вспомогательное действие "выполнить". Например, приложение может предложить пользователю подписаться на службу. PrimaryButton в качестве подтверждающего действия "выполнить" будет содержать текст "Подписаться", а SecondaryButton в качестве нейтрального действия "выполнить" будет содержать текст "Попробовать". CloseButton позволит пользователю отменить операцию без выполнения какого-либо действия.
Когда пользователь нажимает кнопку PrimaryButton, метод ShowAsync возвращает ContentDialogResult.Primary. Когда пользователь нажимает кнопку SecondaryButton, метод ShowAsync возвращает ContentDialogResult.Secondary.
Кнопка по умолчанию
При необходимости можно выделить одну из трех кнопок в качестве кнопки по умолчанию. Если задать кнопку по умолчанию, то происходит следующее.
- Кнопка получает оформление как акцентная кнопка.
- Кнопка автоматически ответит на клавишу ВВОД
- Когда пользователь нажимает клавишу "ВВОД" на клавиатуре, активируется обработчик нажатия, связанный с кнопкой по умолчанию, и ContentDialogResult вернет значение, связанное с этой кнопкой по умолчанию.
- Если пользователь поместил фокус клавиатуры на элемент управления, который обрабатывает кнопку "ВВОД", то кнопка по умолчанию не будет реагировать на нажатия клавиши "ВВОД".
- Фокус перейдет на эту кнопку автоматически при открытии диалогового окна, если содержание диалогового окна не содержит фокусируемых элементов пользовательского интерфейса.
Используйте свойство ContentDialog.DefaultButton, чтобы указать кнопку по умолчанию. По умолчанию кнопка по умолчанию не задана.
private async void DisplaySubscribeDialog()
{
ContentDialog subscribeDialog = new ContentDialog
{
Title = "Subscribe to App Service?",
Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
CloseButtonText = "Not Now",
PrimaryButtonText = "Subscribe",
SecondaryButtonText = "Try it",
DefaultButton = ContentDialogButton.Primary
};
ContentDialogResult result = await subscribeDialog.ShowAsync();
}
Диалоговые окна подтверждения (ОК или отмена)
Диалоговое окно подтверждения дает пользователям возможность подтвердить, что они хотят выполнить действие. Они могут подтвердить действие или отменить. Обычное диалоговое окно подтверждения имеет две кнопки: кнопку подтверждения ("ОК") и кнопку отмены.
-
Как правило, кнопка подтверждения должна находиться слева (основная кнопка), а кнопка отмены (вторичная кнопка) должна находиться справа.
- Как отмечалось в разделе общих рекомендаций, используйте кнопки с текстом, определяющим конкретные ответы на основную инструкцию или содержимое.
Некоторые платформы помещают кнопку подтверждения справа вместо левого. Так почему мы рекомендуем положить его слева? Если предположить, что большинство пользователей правши и держат телефон правой рукой, то на самом деле удобнее нажимать кнопку подтверждения, когда она находится слева, потому что она, скорее всего, окажется в пределах движения большого пальца. Кнопки на правой стороне экрана требуют, чтобы пользователь согнул большой палец в менее удобное положение.
ContentDialog в AppWindow или Xaml Islands
ПРИМЕЧАНИЕ. Этот раздел применяется только к приложениям, предназначенным для Windows 10 версии 1903 или более поздней. Объекты AppWindow и XAML Island недоступны в более ранних версиях. Дополнительные сведения об управлении версиями см. в статье Приложения с адаптивным к версии кодом.
По умолчанию диалоговые окна содержимого модально связаны с корневым объектом ApplicationView. При использовании ContentDialog в объекте AppWindow или XAML Island необходимо вручную задать XamlRoot для диалогового окна, указав корень узла XAML.
Для этого задайте для свойства XamlRoot элемента ContentDialog то же значение XamlRoot, что и у элемента, уже заданного в AppWindow или XAML Island, как показано ниже.
private async void DisplayNoWifiDialog()
{
ContentDialog noWifiDialog = new ContentDialog
{
Title = "No wifi connection",
Content = "Check your connection and try again.",
CloseButtonText = "OK"
};
// Use this code to associate the dialog to the appropriate AppWindow by setting
// the dialog's XamlRoot to the same XamlRoot as an element that is already present in the AppWindow.
if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
noWifiDialog.XamlRoot = elementAlreadyInMyAppWindow.XamlRoot;
}
ContentDialogResult result = await noWifiDialog.ShowAsync();
}
Предупреждение
В каждом потоке в данный момент может быть открыт только один элемент ContentDialog. Попытка открыть два диалоговых окна ContentDialog породит исключение, даже если они пытаются открыться в отдельных окнах AppWindow.
UWP и WinUI 2
Внимание
Сведения и примеры в этой статье оптимизированы для приложений, использующих пакет SDK для приложений Windows и WinUI 3, но обычно применимы к приложениям UWP, использующим WinUI 2. См. справочник по API UWP для конкретных сведений и примеров платформы.
В этом разделе содержатся сведения, необходимые для использования элемента управления в приложении UWP или WinUI 2.
API для этого элемента управления существуют в пространстве имен Windows.UI.Xaml.Controls .
- API UWP:класс ContentDialog
- Откройте приложение коллекции WinUI 2 и просмотрите ContentDialog в действии. Приложения из коллекции WinUI 2 включают интерактивные примеры большинства элементов управления, возможностей и функций WinUI 2. Получите приложение из Microsoft Store или получите исходный код в GitHub.
Мы рекомендуем использовать последнюю версию WinUI 2 , чтобы получить самые актуальные стили и шаблоны для всех элементов управления. WinUI 2.2 или более поздней версии содержит новый шаблон для этого элемента управления, использующего округленные углы. Дополнительные сведения см. в разделе о радиусе угла.
Связанные статьи
Windows developer