This module provides material effect capabilities. You can configure parameters such as the material type and level to achieve diversified material effects.

Since: 6.1.0(23)

Modules to Import

PhonePC/2in1TabletTV

Collapse
Word wrap
Dark theme
Copy code
import { hdsMaterial } from '@kit.UIDesignKit';

getSystemMaterialTypes

PhonePC/2in1TabletTV

getSystemMaterialTypes(): Array<MaterialType>

Obtains all material types supported by the device.

Widget capability: This API can be used in ArkTS widgets since API version 6.1.0(23).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.UIDesign.HDSComponent.Core

Since: 6.1.0(23)

Returns

Expand

Type	Description
Array<MaterialType>	Material types supported by the device.

Example

Collapse
Word wrap
Dark theme
Copy code
import { hdsMaterial } from '@kit.UIDesignKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let materialTypes: Array<hdsMaterial.MaterialType> = hdsMaterial.getSystemMaterialTypes();
} catch (err) {
  let message = (err as BusinessError).message;
  let code = (err as BusinessError).code;
  console.error(`getSystemMaterialTypes failed, code: ${code}, message: ${message}`);
}

MaterialType

PhonePC/2in1TabletTV

Enumerates material types.

Widget capability: This API can be used in ArkTS widgets since API version 6.1.0(23).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.UIDesign.HDSComponent.Core

Since: 6.1.0(23)

Expand

Name	Value	Description
NONE	0	No material effect.
ADAPTIVE	100	Adaptive system material. The immersive material is used by default.
IMMERSIVE	101	Immersive material (new material).

MaterialLevel

PhonePC/2in1TabletTV

Enumerates material levels. The effect of each level is carried on the component that supports material attribute configuration. The exquisite material consumes more performance, while the smooth material consumes less performance.

Widget capability: This API can be used in ArkTS widgets since API version 6.1.0(23).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.UIDesign.HDSComponent.Core

Since: 6.1.0(23)

Expand

Name	Value	Description
EXQUISITE	0	Exquisite.
GENTLE	1	Gentle.
SMOOTH	2	Smooth.
ADAPTIVE	10	The material effect policy is determined by the system. The system adapts the material level based on the device performance.

NOTE

The default value ADAPTIVE is recommended. In this mode, the system dynamically adjusts the material effect of the component based on the computing power of the current device, achieving the optimal balance between performance and display effect.
If the system adaptation capability is not used, call the getSystemMaterialTypes() API to query the material capabilities supported by the current device, and then select the corresponding material effect enumeration based on the query result.
- If the query result indicates that the current device supports the IMMERSIVE material type, you can use the EXQUISITE or GENTLE effect.
- If the query result indicates that the current device does not support the IMMERSIVE material type, you are advised to use the SMOOTH effect to reduce stuttering and heat risks and ensure user experience.
Detailed usage guide: For details, see [HDS Component Guide to Using Immersive Light Materials].

hdsEffect

ArkTS API Error Codes

Send feedback

Was this page helpful?

Send feedback

Reach out to us through the community for any other questions.

Community Q&A Intelligent Assistant