Introduction to the next Scoring Component

Scoring Component Introduction

The Scoring (Rating) component is a versatile UI element designed to allow users to provide ratings or feedback through a series of stars. It is widely used in applications such as reviews, feedback forms, and user interactions. This component offers a range of customizable properties and events that enable developers to tailor its appearance and behavior to fit their specific needs.

Properties

stars

• Description: Sets the total number of rating stars. If a value less than or equal to 0 is provided, the default value of 5 is used.
• Card Ability: Supported in ArkTS cards from API version 9.
• Meta-service API: Supported in meta-services from API version 11.
• System Capability: SystemCapability.ArkUI.ArkUI.Full
• Parameters:
  • value: number (Required) - The total number of rating stars. Default: 5.

stepSize

• Description: Sets the step size for rating operations. If a value less than 0.1 is provided, the default value of 0.5 is used. This property determines the granularity of the rating increments.
• Card Ability: Supported in ArkTS cards from API version 9.
• Meta-service API: Supported in meta-services from API version 11.
• System Capability: SystemCapability.ArkUI.ArkUI.Full
• Parameters:
  • value: number (Required) - The step size for rating operations. Default: 0.5. Range: [0.1, stars].

starStyle

• Description: Sets the style for the rating stars. This property allows customization of the appearance of the stars using images.
• Supported Image Types: Local and network images are supported. PixelMap type and Resource resources are not supported.
• Default Behavior: Images are loaded asynchronously. Synchronous loading is not supported.
• Card Ability: Supported in ArkTS cards from API version 9.
• Meta-service API: Supported in meta-services from API version 11.
• System Capability: SystemCapability.ArkUI.ArkUI.Full
• Parameters:
  • value: {backgroundUri: string, foregroundUri: string, secondaryUri?: string} (Required)
  • backgroundUri: The image link for unselected stars. Can be custom-defined or use the system default.
  • foregroundUri: The image path for selected stars. Can be custom-defined or use the system default.
  • secondaryUri: The image path for partially selected stars. Can be custom-defined or use the system default.
  • If the image path for backgroundUri, foregroundUri, or secondaryUri is incorrect, the image will not be displayed. If backgroundUri or foregroundUri is set to undefined or an empty string, the system default star image will be loaded. If secondaryUri is not set or is undefined or an empty string, it will prioritize being set to backgroundUri, which is equivalent to only setting foregroundUri and backgroundUri.

contentModifier

• Description: A method for customizing the content area of the Rating component. This allows developers to implement custom behavior for the rating component.
• System Capability: SystemCapability.ArkUI.ArkUI.Full
• Parameters:
  • modifier: ContentModifier (Required) - A content modifier that developers need to implement by defining a custom class to realize the ContentModifier interface.

Events

onChange

• Description: Triggers this callback when the rating stars change. This event is useful for capturing user input and updating the application state accordingly.
• Card Ability: Supported in ArkTS cards from API version 9.
• Meta-service API: Supported in meta-services from API version 11.
• System Capability: SystemCapability.ArkUI.ArkUI.Full
• Parameters:
  • value: number (Required) - The rating value.

Keyboard Focus Specification

The Scoring component supports keyboard navigation, allowing users to interact with the rating stars using the following keys:

• Tab: Switch focus between components.
• Left/Right Arrow Keys: Increase or decrease the rating preview (step size is stepSize) without changing the actual rating.
• Home: Move to the first star without changing the actual rating.
• End: Move to the last star without changing the actual rating.
• Space/Enter: Submit the rating result based on the current rating.

Example Usage

Here is an example of how to use the Scoring component in an ArkTS application:

import { Scoring } from 'ohos.ui';

// Create a Scoring instance
const scoring = new Scoring(context);

// Set the total number of rating stars
scoring.stars = 5;

// Set the step size for rating operations
scoring.stepSize = 0.5;

// Set the style for the rating stars
scoring.starStyle = {
  backgroundUri: 'path/to/unselected_star.png', // Image for unselected stars
  foregroundUri: 'path/to/selected_star.png',  // Image for selected stars
  secondaryUri: 'path/to/partially_selected_star.png' // Image for partially selected stars
};

// Add an event listener for rating changes
scoring.onChange = (value) => {
  console.log('Rating changed to: ' + value);
};

// Show the Scoring component
scoring.show();

Detailed Explanation

1. Creating a Scoring Instance:

   const scoring = new Scoring(context);

This line creates a new instance of the Scoring component. The context parameter provides the necessary runtime environment information.

1. Setting the Total Number of Rating Stars:

   scoring.stars = 5;

This sets the total number of rating stars to 5. You can change this value to any positive integer.

1. Setting the Step Size:

   scoring.stepSize = 0.5;

This sets the step size for rating operations to 0.5. This means users can rate in half-star increments.

1. Setting the Star Style:

   scoring.starStyle = {
     backgroundUri: 'path/to/unselected_star.png',
     foregroundUri: 'path/to/selected_star.png',
     secondaryUri: 'path/to/partially_selected_star.png'
   };

This customizes the appearance of the rating stars using images. The backgroundUri is the image for unselected stars, foregroundUri is for selected stars, and secondaryUri is for partially selected stars.

1. Adding an Event Listener:

   scoring.onChange = (value) => {
     console.log('Rating changed to: ' + value);
   };

This adds an event listener to handle changes in the rating value. The onChange callback is triggered whenever the user changes the rating.

1. Displaying the Scoring Component:

   scoring.show();

This displays the Scoring component on the screen.

Customizing the Scoring Component

You can further customize the Scoring component by implementing a ContentModifier to modify its content area dynamically. This allows for more advanced interactions and visual effects.

Conclusion

The Scoring component is a powerful and flexible tool for collecting user feedback in HarmonyOS applications. By leveraging its customizable properties, events, and keyboard navigation support, developers can create intuitive and user-friendly rating interfaces. Whether you are building a review system, a feedback form, or any other application that requires user ratings, the Scoring component provides a robust solution to meet your needs.