From 4380a22cef45eed059e4624f156a003f312ceb58 Mon Sep 17 00:00:00 2001 From: David Britch Date: Wed, 4 Dec 2024 09:53:43 +0000 Subject: [PATCH] OnPlatform and OnIdiom trim incompatibilities (#2659) * OnPlatform and OnIdiom trim incompatibilities. * Fix links. * Fix linting error. * Fix bookmarks. * Edit. * Edit. --- .../includes/trimming-incompatibilities.md | 4 +- docs/deployment/nativeaot.md | 6 +- docs/deployment/trimming.md | 2 +- .../customize-ui-appearance.md | 126 +++++++++++++++++- 4 files changed, 128 insertions(+), 10 deletions(-) diff --git a/docs/deployment/includes/trimming-incompatibilities.md b/docs/deployment/includes/trimming-incompatibilities.md index 0054005a4..bf826f1c1 100644 --- a/docs/deployment/includes/trimming-incompatibilities.md +++ b/docs/deployment/includes/trimming-incompatibilities.md @@ -1,6 +1,6 @@ --- ms.topic: include -ms.date: 11/14/2024 +ms.date: 12/03/2024 monikerRange: ">=net-maui-9.0" --- @@ -12,3 +12,5 @@ The following .NET MAUI features are incompatible with full trimming and will be - Receiving navigation data using the . Instead, you should implement the interface on types that need to accept query parameters. For more information, see [Process navigation data using a single method](~/fundamentals/shell/navigation.md#process-navigation-data-using-a-single-method). - The `SearchHandler.DisplayMemberName` property. Instead, you should provide an to define the appearance of results. For more information, see [Define search results item appearance](~/fundamentals/shell/search.md#define-search-results-item-appearance). - The control, due to its use of dynamic `System.Text.Json` serialization features. +- UI customization with the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) XAML markup extension. Instead, you should use the class. For more information, see [Customize UI appearance based on the platform](~/platform-integration/customize-ui-appearance.md#customize-ui-appearance-based-on-the-platform). +- UI customization with the [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) XAML markup extension. Instead, you should use the class. For more information, see [Customize UI appearance based on the device idiom](~/platform-integration/customize-ui-appearance.md#customize-ui-appearance-based-on-the-device-idiom). diff --git a/docs/deployment/nativeaot.md b/docs/deployment/nativeaot.md index 1aee13bda..1de7f2c87 100644 --- a/docs/deployment/nativeaot.md +++ b/docs/deployment/nativeaot.md @@ -1,7 +1,7 @@ --- title: "Native AOT deployment on iOS and Mac Catalyst" description: "Learn how to reduce your app size and achieve faster startup time with native AOT deployment on iOS and Mac Catalyst." -ms.date: 11/12/2024 +ms.date: 12/03/2024 monikerRange: ">=net-maui-9.0" --- @@ -110,6 +110,8 @@ In .NET MAUI app this means that: - It's not possible to parse XAML at runtime with the method. While this can be made trim safe by annotating all types that could be loaded at runtime with the [`DynamicallyAccessedMembers`](xref:System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute) attribute or the [`DynamicDependency`](xref:System.Diagnostics.CodeAnalysis.DynamicDependencyAttribute) attribute this is very error prone and isn't recommended. - Receiving navigation data using the won't work. Instead, you should implement the interface on types that need to accept query parameters. For more information, see [Process navigation data using a single method](~/fundamentals/shell/navigation.md#process-navigation-data-using-a-single-method). - The `SearchHandler.DisplayMemberName` property might not work. Instead, you should provide an to define the appearance of results. For more information, see [Define search results item appearance](~/fundamentals/shell/search.md#define-search-results-item-appearance). +- Customizing UI appearance with the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) XAML markup extension isn't possible. Instead, you should use the class. For more information, see [Customize UI appearance based on the platform](~/platform-integration/customize-ui-appearance.md#customize-ui-appearance-based-on-the-platform). +- Customizing UI appearance with the [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) XAML markup extension isn't possible. Instead, you should use the class. For more information, see [Customize UI appearance based on the device idiom](~/platform-integration/customize-ui-appearance.md#customize-ui-appearance-based-on-the-device-idiom). > [!IMPORTANT] > The Mono interpreter isn't compatible with Native AOT deployment, and therefore the `$(UseInterpreter)` and `$(MtouchInterpreter)` MSBuild properties have no effect when using Native AOT. For more information about the Mono interpreter, see [Mono interpreter on iOS and Mac Catalyst](~/macios/interpreter.md). @@ -129,6 +131,8 @@ Use the following checklist to help you adapt your app to Native AOT deployment > - Ensure that all data bindings are compiled. For more information, see [Compiled bindings](~/fundamentals/data-binding/compiled-bindings.md). > - Ensure that all XAML data bindings are annotated with `x:DataType`. > - Ensure that all code data bindings replace all string-based bindings with lambda-based bindings. +> - Replace all [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) XAML markup extension usage with an implementation that uses the class. For more information, see [Customize UI appearance based on the platform](~/platform-integration/customize-ui-appearance.md#customize-ui-appearance-based-on-the-platform). +> - Replace all [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) XAML markup extension usage with an implementation that uses the class. For more information, see [Customize UI appearance based on the device idiom](~/platform-integration/customize-ui-appearance.md#customize-ui-appearance-based-on-the-device-idiom). > - Replace all `[QueryProperty(...)]` usage with an implementation of the `IQueryAttributable` interface. For more information, see [Process navigation data using a single method](~/fundamentals/shell/navigation.md#process-navigation-data-using-a-single-method). > - Replace all `SearchHandler.DisplayMemberName` usage with an . For more information, see [Define search results item appearance](~/fundamentals/shell/search.md#define-search-results-item-appearance). > - Replace all implicit conversion operators for types used in XAML with a , and it attach it to your type using the . For more information, see [Define a TypeConverter to replace an implicit conversion operator](trimming.md#define-a-typeconverter-to-replace-an-implicit-conversion-operator). diff --git a/docs/deployment/trimming.md b/docs/deployment/trimming.md index 805bfff95..67917cd6f 100644 --- a/docs/deployment/trimming.md +++ b/docs/deployment/trimming.md @@ -1,7 +1,7 @@ --- title: "Trim a .NET MAUI app" description: "Learn about the .NET trimmer, which eliminates unused code from a .NET MAUI app to reduce its size." -ms.date: 10/24/2024 +ms.date: 12/03/2024 no-loc: [ ILLink ] monikerRange: ">=net-maui-9.0" --- diff --git a/docs/platform-integration/customize-ui-appearance.md b/docs/platform-integration/customize-ui-appearance.md index 52798010e..975116f89 100644 --- a/docs/platform-integration/customize-ui-appearance.md +++ b/docs/platform-integration/customize-ui-appearance.md @@ -1,7 +1,7 @@ --- title: "Customize UI appearance based on the platform and device idiom" description: "Learn how the OnPlatform and OnIdiom XAML markup extensions enable you to customize UI appearance on a per-platform and per-device basis." -ms.date: 04/18/2023 +ms.date: 12/03/2024 --- # Customize UI appearance based on the platform and device idiom @@ -14,13 +14,109 @@ ms.date: 04/18/2023 - Take advantage of device capabilities. Certain devices are more likely to have certain capabilities. For example, mobile devices are more likely to have a location sensor and a camera, while desktop devices might not have either. Your app can detect which capabilities are available and enable controls that use them. - Optimize for input. You can rearrange your UI elements to optimize for specific input types. For example, if you place navigation elements at the bottom of the app, they'll be easier for mobile users to access. But desktop users often expect to see navigation elements towards the top of the app. -When you optimize your app's UI for specific platforms and device idioms, you're creating a responsive UI. The primary approaches to creating a responsive UI in .NET MAUI involve using the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extension and the [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) markup extension. +When you optimize your app's UI for specific platforms and device idioms, you're creating a responsive UI. The primary approach to creating a responsive UI in .NET MAUI involves using the and classes. An alternative approach is to use the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) and [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) XAML markup extensions. However, these markup extensions aren't trim safe. For more information about the markup extensions, see [Customize UI appearance with markup extensions](#customize-ui-appearance-with-markup-extensions). > [!NOTE] > There is a category of triggers, known as state triggers, that can be used to customize UI appearance in specific scenarios such as when the orientation of a device changes. For more information, see [State trigger](~/fundamentals/triggers.md#state-trigger). ## Customize UI appearance based on the platform +The and classes enable you to customize UI appearance on a per-platform basis: + +```xaml + + + + + + + + ... + +``` + + is a generic class and so you need to specify the generic type argument, in this case, , which is the type of `Padding` property. This is achieved with the `x:TypeArguments` XAML attribute. The class defines a property that can be set to a value that will be applied to all platforms: + +```xaml + + + + + + + + ... + +``` + +In this example, the `Padding` property is set to different values on iOS and Android, with the other platforms being set to the default value. + +The class also defines a property, which is an `IList` of objects. Each object can set the and property to define the value for a specific platform. In addition, the property is of type `IList`, so you can include multiple comma-delimited platforms if the values are the same: + +```xaml + + + + + + + ... + +``` + +Providing an incorrect value won't result in an error. Instead, your XAML will execute without the platform-specific value being applied. + +> [!NOTE] +> If the `Value` property of an `On` object can't be represented by a single string, you can define property elements for it. + +## Customize UI appearance based on the device idiom + +The class enables you to customize UI appearance based on the idiom of the device the app is running on: + +```xaml + + + + 0,20,0,0 + 0,40,0,0 + 0,60,0,0 + + + ... + +``` + + is a generic class and so you need to specify the generic type argument, in this case, , which is the type of `Margin` property. This is achieved with the `x:TypeArguments` XAML attribute. The class defines a property that can be set to a value that will be applied to all platforms: + +```xaml + + + + 0,60,0,0 + + + ... + +``` + +In this example, the `Margin` property is set to a specific value on desktop idioms, with the other idioms being set to the default value. + +## Customize UI appearance with markup extensions + +UI appearance can also be customized with the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) and [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) markup extensions. However, these markup extensions aren't trim safe. + +### Customize UI appearance with a markup extension based on the platform + The [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extension enables you to customize UI appearance on a per-platform basis. It provides the same functionality as the and classes, but with a more concise representation. The [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extension is supported by the class, which defines the following properties: @@ -42,7 +138,7 @@ The `Default` property is the content property of [!IMPORTANT] > The XAML parser expects that values of the correct type will be provided to properties consuming the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extension. If type conversion is necessary, the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extension will attempt to perform it using the default converters provided by .NET MAUI. However, there are some type conversions that can't be performed by the default converters and in these cases the `Converter` property should be set to an implementation. -The **OnPlatform Demo** page shows how to use the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extension: +The following XAML example shows how to use the [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extension: ```xaml ``` -In this example, all three [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) expressions use the abbreviated version of the class name. The three [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extensions set the `xref:Microsoft.Maui.Graphics.Color`, , and properties of the to different values on iOS and Android. The markup extensions also provide default values for these properties on the platforms that aren't specified, while eliminating the `Default=` part of the expression. +In this example, all three [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) expressions use the abbreviated version of the class name. The three [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extensions set the , , and properties of the to different values on iOS and Android. The markup extensions also provide default values for these properties on the platforms that aren't specified, while eliminating the `Default=` part of the expression. -## Customize UI appearance based on the device idiom +::: moniker range=">=net-maui-9.0" + +> [!WARNING] +> The [`OnPlatform`](xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension) markup extension isn't trim safe and shouldn't be used with full trimming or NativeAOT. Instead, you should use the class to customize UI appearance on a per-platform basis. For more information, see [Customize UI appearance based on the platform](#customize-ui-appearance-based-on-the-platform), [Trim a .NET MAUI app](~/deployment/trimming.md) and [Native AOT deployment](~/deployment/nativeaot.md). + +::: moniker-end + +### Customize UI appearance with a markup extension based on the device idiom -The [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) markup extension enables you to customize UI appearance based on the idiom of the device the app is running on. It's supported by the class, which defines the following properties: +The [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) markup extension enables you to customize UI appearance based on the idiom of the device the app is running on. It provides the same functionality as the class, but with a more concise representation. + +The [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) markup extension is supported by the class, which defines the following properties: - `Default`, of type `object`, that you set to a default value to be applied to the properties that represent device idioms. - `Phone`, of type `object`, that you set to a value to be applied on phones. @@ -83,4 +188,11 @@ The following XAML example shows how to use the [`OnIdiom`](xref:Microsoft.Maui. HorizontalOptions="Center" /> ``` -In this example, all three [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) expressions use the abbreviated version of the class name. The three [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) markup extensions set the `Color`, , and properties of the to different values on the phone, tablet, and desktop idioms. The markup extensions also provide default values for these properties on the idioms that aren't specified, while eliminating the `Default=` part of the expression. +In this example, all three [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) expressions use the abbreviated version of the class name. The three [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) markup extensions set the , , and properties of the to different values on the phone, tablet, and desktop idioms. The markup extensions also provide default values for these properties on the idioms that aren't specified, while eliminating the `Default=` part of the expression. + +::: moniker range=">=net-maui-9.0" + +> [!WARNING] +> The [`OnIdiom`](xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension) markup extension isn't trim safe and shouldn't be used with full trimming or NativeAOT. Instead, you should use the class to customize UI appearance based on the idiom of the device the app is running on. For more information, see [Customize UI appearance based on the device idiom](#customize-ui-appearance-based-on-the-device-idiom), [Trim a .NET MAUI app](~/deployment/trimming.md) and [Native AOT deployment](~/deployment/nativeaot.md). + +::: moniker-end