开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

XF.Material Library

A Xamarin.Forms library for Xamarin.Android and Xamarin.iOS to implement Google's Material Design.

Support

• Feel free to open an issue. Make sure to use one of the templates!
• Commercial support is available. Integration with your app or services, samples, feature request, etc. Email: [email protected]
• Powered by: baseflow.com

Contents

• Getting Started
• Features
  • Material UI
    • App Bar Customization
    • Cards
    • Buttons
    • Text Fields
    • Selection Controls
    • Menus
    • Slider
    • Switch
    • Typography Label
    • Chips
    • Circular Progress Indicator
    • Tintable Image Icon
  • Material Dialogs
    • Alert Dialog
    • Simple Dialog
    • Confirmation Dialog
    • Input Dialog
    • Loading Dialog
    • Snackbar
    • Styling Dialogs
  • Material Resources
    • Color
    • Typography
    • Adding the Material Resources
    • Retrieving a Material Resource
  • Changing the Status Bar Color
• Android Compatibility Issues
• Thanks and Appreciation

Getting Started

1. Download the current version through NuGet and install it in your Xamarin.Forms projects.
2. Call the Material.Init() method in each project:

//Xamarin.Forms

public App()
{
    this.InitializeComponent();
    XF.Material.Forms.Material.Init(this);
}

//Xamarin.Android

protected override void OnCreate(Bundle savedInstanceState)
{
    TabLayoutResource = Resource.Layout.Tabbar;
    ToolbarResource = Resource.Layout.Toolbar;

    base.OnCreate(savedInstanceState);

    Xamarin.Forms.Forms.Init(this, savedInstanceState);
    XF.Material.Droid.Material.Init(this, savedInstanceState);

    this.LoadApplication(new App());
}

//Xamarin.iOS

public override bool FinishedLaunching(UIApplication app, NSDictionary options)
{
    Xamarin.Forms.Forms.Init();
    XF.Material.iOS.Material.Init();
    this.LoadApplication(new App());

    return base.FinishedLaunching(app, options);
}

3. Configure your application's color and font resources. Read more about it here.

Additional configuration for iOS

In order to be able to change the status bar's colors using this or by setting your app colors here, add this to your info.plist file:

<key>UIViewControllerBasedStatusBarAppearance</key>
<false/>

Note: If some of the controls like progressbar, checkbox and radio buttons are not showing in iOS then add all the files from here to iOS project's Resources folder.

Features

Material UI

Under the XF.Material.Forms.UI namespace, the library offers a number of controls available.

App Bar Customization

You can customize the appearance of the App Bar by using the MaterialNavigationPage control.

Code	Android	iOS
<ContentPage .... xmlns:material="clr-namespace:XF.Material.Forms.UI;assembly=XF.Material" material:MaterialNavigationPage.AppBarColor="#2c3e50" material:MaterialNavigationPage.AppBarTitleTextFontFamily="Roboto" material:MaterialNavigationPage.AppBarTitleTextFontSize="14" material:MaterialNavigationPage.StatusBarColor="#1B3147" material:MaterialNavigationPage.AppBarTitleTextAlignment="Start" /* Content goes here * </ ContentPage>

Attached Properties

These are attached properties that can be used on pages that are navigated through the MaterialNavigationPage control.

1. AppBarColor - The color of the app bar.

2. AppBarTitleTextAlignment - The text alignment of the app bar title. The default value is TextAlignment.Start.

3. AppBarTitleTextColor - The text color of the app bar title. The default value is Material.Color.OnPrimary.

4. AppBarTitleFontFamily - The font family of the app bar title. The default value is Material.FontFamily.H6.

5. AppBarTitleFontSize - The font size of the app bar title. The default value is 24.

6. AppBarElevation - The size of the shadow below the app bar. The default value is 4.

7. StatusBarColor - The color of the status bar.

Usage and Behavior

This control uses the new feature of Xamarin 3.3, the TitleView property, to be able to change the appearance of the app bar title. But when the TitleView property is set on a page, the attached properties will not work.

Cards

Cards contain content and actions about a single subject.

Code	Android	iOS
<material:MaterialCard CornerRadius="2" Elevation="1" HeightRequest="80" HorizontalOptions="FillAndExpand" />

Property

MaterialCard inherits the Frame class.

• Elevation - The virtual distance along the z-axis. The value determines the importance of the content pesented in this view. The default value is 1.

• IsClickable - When set to true, the card displays a ripple-effect when touched.

• ClickCommand - The command that will run when this card was touched and the property IsClickable is set to true.

• ClickCommandParameter - The parameter to pass in ClickCommand when it is executed.

Event

• Clicked - The event that is raised when this card was touched and the property IsClickable is set to true.

Usage

Cards are surfaces that display content and actions on a single topic. They should be easy to scan for relevant and actionable information. Elements, like text and images, should be placed on them in a way that clearly indicates hierarchy.

Read more about cards here.

Buttons

Buttons allow users to take actions, and make choices, with a single tap.

There are two types of buttons you can use: MaterialButton and MaterialIconButton

Code	Android	iOS
<material:MaterialButton BackgroundColor="#EAEAEA" HorizontalOptions="Center" Text="Elevated Button" TextColor="Black" VerticalOptions="Center" />

Properties

MaterialButton inherits the Button class. MaterialIconButton inherits the ContentView class.

Both of these controls have these common properties:

1. ButtonType - The type of the button. The default value is Elevated.

   • Elevated - This button will cast a shadow.
   • Flat - This button will have no shadow.
   • Outlined - This button will have no shadow, has a transparent background, and has a border.
   • Text - This button will only show its label. It will not have a shadow, has a transparent background, and no border. Text buttons has a smaller inner padding as compared to the other button types.

2. BackgroundColor - The color of the button's background. Outlined and Text button types will always have a transparent background color. Flat and elevated buttons have a default background color based on the value of MaterialColorConfiguration.Secondary.

3. PressedBackgroundColor - The color of the button's background when it is pressed.

4. DisabledBackgroundColor - The color of the button's background when it is disabled.

5. Elevation - The virtual distance along the z-axis.

MaterialButton have these properties:

1. Image - The icon to be displayed next to the button's label. The color of the icon will be based on the TextColor property value of the button.

2. AllCaps - Whether the letters in the label of the button should be in upper case or not. By default, this is set to true.

MaterialIconButton has this property:

1. Image - The image of the button.

2. TintColor - The tint color of the image.

Usage & Behavior

Buttons communicate actions that users can take. They are typically placed throughout your UI.

• Elevated and Flat

  

  These are high-emphasis buttons that are distinguished by their fill color and/or shadow. The actions bound to them are primary to your app.

• Outlined

  

  These are medium-emphasis buttons. The actions bound to them are important, but are not the primary action in an app.

• Text

  

  These buttons are typically used for less-pronounced actions, which are located in modal dialogs or in cards.

You can set the Elevation property of the button using XAML or C# code. You can also set values when the button is in normal state or pressed state.

Using XAML

<!-- Button with a normal and pressed elevation of `4` -->
<material:MaterialButton Elevation="4" Text="Click" />

<!-- Button with a normal elevation of `4` and pressed elevation of `8` -->
<material:MaterialButton Elevation="4, 8" Text="Click" />

Using C#

// Button with a normal and pressed elevation of `4`
var button1 = new MaterialButton()
{
    Elevation = new MaterialElevation(4),
    Text = "Click"
};

// Button with a normal and pressed elevation of `4` using implicit operator
var button2 = new MaterialButton()
{
    Elevation = 4,
    Text = "Click"
};

// Button with a normal elevation of `4` and pressed elevation of `8`
var button3 = new MaterialButton()
{
    Elevation = new MaterialElevation(4,8),
    Text = "Click"
};

On press, buttons display touch feedback (ripple effect).

Read more about buttons here.

Text Fields

Text fields allow users to enter and edit text.

Code	Android	iOS
<material:MaterialTextField Placeholder="Placeholder" HelperText="Helper Text" ErrorText="Error Text" Text="Input Text" InputType="Default" />

Properties

MaterialTextField inherits the ContentView class.

1. AlwaysShowUnderline - Boolean flag determines whether the underline accent of this text field should always show or not. The default value is false.

2. BackgroundColor - The background color of the text field. Default hex color value is #DCDCDC.

3. ErrorColor - The color to indicate an error in the text field. The default value is based on the color value of MaterialColorConfiguration.Error.

4. ErrorText - The text that will show to indicate an error in this text field. This will replace HelperText when HasError is set to true.

5. ErrorIcon - The icon that will show to indicate an error in this text field. Will show when HasError is set to true.

6. FocusCommand - The command that will be executed when this text field receives or loses focus.

7. HasError - Boolean flag that indicates whether an error has occurred or not in this text field.

8. HelperText - The text that appears below the text field to indicate additional hints for the text field.

9. HelperTextColor - The color of the helper text. The default hex color value is #99000000.

10. HelperTextFontFamily - The font family of the helper text. The ErrorText will use this as its font family.

11. LeadingIcon - The image icon that will show on the left side of this text field.

12. LeadingIconTintColor - The color to be used to tint the icon image of this text field. The default hex color value is #99000000.

13. InputType - The keyboard input type to be used for this text field.

14. MaxLength - The maximum allowed number of characters in this text field.

15. Placeholder - The placeholder text of this text field. This property must never be null or empty.

16. PlaceholderColor - The color of the placeholder text. The default hex color value is #99000000.

17. ReturnType - The appearance of the return button of the keyboard.

18. ReturnCommand - The command that will run when the user returns the input.

19. ReturnCommandParameter - The parameter to be passed in ReturnCommand property when it is executed.

20. Text - The input text of this text field.

21. TextChangeCommand - The command that executes when there is a change in this text field's input text.

22. TextColor - The color of the input text. The default hex color value is #D0000000.

23. TextFontFamily - The font family of the input text. By default, it uses the MaterialFontConfiguration.Body2 font family.

24. TintColor - The tint color of the underline accent and the placeholder of this text field when focused. The default color is set to the value of MaterialColorConfiguration.SecondaryColor.

25. FloatingPlaceholderEnabled - Determines whether the placeholder should float above when the text field is focused.

26. Choices - When the InputType property is set to MaterialInputType.Choice, provides the list of choices from which the user will select one.

27. ChoicesBindingName - The name of the property of the items in the Choices property to display.

28. ChoiceSelectedCommand - The command that will execute when an item is selected using the input type Choice. The parameter that will be passed to this command is the selected item.

29. HorizontalPadding - The value that determines the left and right padding of the text field.

30. IsSpellCheckEnabled - Boolean flag determines whether spell checking is enabled in this text field.

31. IsTextPredictionEnabled - Boolean flag determines whether text prediction is enabled in this field.

32. TextFontSize - The font size of the text field's input text.

33. FloatingPlaceholderFontSize - The font size of the text field's floating placeholder.

34. FloatingPlaceholderColor - The color of the text field's floating placeholder.

35. IsAutocapitalizationEnabled - Boolean value that determines whether to autocapitalize the input text or not.

36. IsMaxLengthCounterVisible - Boolean value that determines whether to show the max input length counter on not.

37. ShouldAnimateUnderline - Boolean value that determines whether to anumate the underline indicator or not.

Events

1. Focused - Raised when this text field receives focus.

2. Unfocused - Raised when this text field loses focus.

3. TextChanged - Raised when the input text of this text field has changed.

4. ChoiceSelected - The event that will be raised when an item is selected using the input type Choice. Gives the item that was selected.

5. Completed - The event that will be raised when the user completes the input using the return key.

Usage and Behavior

A text field container, by default, has a fill. You can make the text field's BackgroundColor transparent and AlwaysShowUnderline to true.

The placeholder text should always be visible, because it is used to inform users as to what information is requested for a text field.

Helper text conveys additional guidance about the input field, such as how it will be used. It should only take up a single line, being persistently visible or visible only on focus.

When input text isn�t accepted, an error text can display instructions on how to fix it. Error messages are displayed below the input line, replacing helper text until fixed.

Read more about text fields here.

Selection Controls

Selection controls allow users to complete tasks that involve making choices such as selecting options, or switching settings on or off. Selection controls are found on screens that ask users to make decisions or declare preferences such as settings or dialogs.

Radio Buttons

Allow users to select one option from a set.

Code	Android	iOS
<material:MaterialRadioButtonGroup x:Name="radioButtonGroup" Choices="{Binding Jobs}" />

Properties

1. Choices - The list of string the user will choose from.

2. FontFamily - The font family of the text of each radio buttons. The default is the value of MaterialFontConfiguration.Body1.

3. FontSize - The font size of the text of each radio buttons. The default value is 16.

4. HorizontalSpacing - The spacing between the radio button and its text.

5. SelectedColor - The color that will be used to tint this control whe selected. The default is the value of MaterialColorConfiguration.Secondary.

6. SelectedIndex - The index of the selected choice.

7. SelectedIndexChanged - Raised when there is a change in the control's selected index.

8. SelectedIndexChangedCommand - The command that wil run if there is a change in the control's selected index. The parameter is the selected index.

9. TextColor - The color of the text of each radio button. The default value is #DE000000.

10. UnselectedColor - The color that will be used to tint this control when unselected. The default value is #84000000.

11. VerticalSpacing - The spacing between each radio buttons.

Usage and Behavior

Use radio buttons when the user needs to see all available options. The orientation of the radio buttons is limited to vertical position, since the custom view used to present the radio buttons is a ListView, but the scroll bars will not show since the ListView's height is based on the number of choices. Each radio button has a fixed height of 48.

Checkboxes

Checkboxes allow the user to select one or more items from a set.

Code	Android	iOS
<material:MaterialCheckboxGroup x:Name="checkBoxGroup" Choices="{Binding Jobs}" />

Properties

1. Choices - The list of string the user will choose from.

2. FontFamily - The font family of the text of each checkboxes. The default is the value of MaterialFontConfiguration.Body1.

3. FontSize - The font size of the text of each checkboxes. The default value is 16.

4. HorizontalSpacing - The spacing between the checkbox and its text.

5. SelectedColor - The color that will be used to tint this control whe selected. The default is the value of MaterialColorConfiguration.Secondary.

6. SelectedIndices - The indices of the selected choices.

7. SelectedIndicesChanged - Raised when there is a change in the control's selected inices.

8. SelectedIndicesChangedCommand - The command that wil run if there is a change in the control's selected indices. The parameter is the list of selected indices.

9. TextColor - The color of the text of each radio button. The default value is #DE000000.

10. UnselectedColor - The color that will be used to tint this control when unselected. The default value is #84000000.

11. VerticalSpacing - The spacing between each checkboxes.

Usage and Behavior

It has the same limitations as MaterialRadioButtonGroup.

Checkboxes can be used to turn an option on or off. If there is only one option, you can use MaterialCheckbox instead.

MaterialCheckbox has the property IsSelected, you can use this to determine whether the option was selected or not.

Menus

Menus display a list of choices on temporary surfaces.

Code	Android	iOS
<material:MaterialMenuButton ButtonType="Text" CornerRadius="24" Choices="{Binding Actions}" Command="{Binding MenuCommand}" />

Properties

MaterialMenuButton inherits the XF.Material.Forms.UI.MaterialIconButton class.

1. Choices - The list of items from which the user will choose from. You can either assign a collection of string or MaterialMenuItem.

2. MenuBackgroundColor - The background color of the menu.

3. MenuCornerRadius - The corner radius of the menu.

4. Command - The command that will execute when a menu item was selected. The type is Command<MaterialMenuResult>. The result will contain the index of the selected menu and the parameter, if any.

5. CommandParameter - The parameter to pass in Command property.

6. MenuTextColor - The text color of the menu items.

7. MenuTextFontFamily - The text font family of the menu items.

Event

1. MenuSelected - Raised when a menu item was selected.

Usage and Behavior

Menus are positioned relative to both the element that generates them and the edges of the screen. They can appear in front of, beside, above, or below the element that generates them.

Menus can be dismissed by tapping outside, when an item was selected, or when the back button was pressed in Android.

Be sure to always match the width and height of the child view to the width and height of the menu.

Menu is by default a button. In the menu sample shown above the 3 dots is an added image. This is one of the possibilities how the menu can look like.

Slider

Sliders allow users to make selections from a range of values.

<mat:MaterialSlider Value="{Binding CurrentValue}" MinValue="0" MaxValue="100" />

Properties

MaterialSlider inherits the ContentView class.

1. Value - The current v