1# Dark and Light Mode Adaptation 2 3## Overview 4 5To enhance user experience, applications should adapt to the system's dark and light modes. There are two primary scenarios for implementing this adaptation: 6 7[Following the System's Color Mode](#following-the-systems-color-mode) 8 9[Setting the Application's Color Mode Independently](#setting-the-applications-color-mode-independently) 10 11## Following the System's Color Mode 12 131. Color Adaptation 14 15 - Custom Resource Implementation 16 17 Create a **dark** folder under the **resources** directory and add a **color.json** file to define dark mode color resources. For details, see [Resource Categories and Access](../quick-start/resource-categories-and-access.md). 18 19 Figure 1 Structure of the resources directory 20 21  22 23 The following is the example configuration: 24 25 **base/element/color.json** file: 26 27 ```json 28 { 29 "color": [ 30 { 31 "name": "app_title_color", 32 "value": "#000000" 33 } 34 ] 35 } 36 ``` 37 38 **dark/element/color.json** file: 39 40 ```json 41 { 42 "color": [ 43 { 44 "name": "app_title_color", 45 "value": "#FFFFFF" 46 } 47 ] 48 } 49 ``` 50 51 - System Resource Implementation 52 53 You can use [system-provided resources](../quick-start/resource-categories-and-access.md#system-resources), which automatically adapt to different configurations including the device type and dark or light mode. The same resource ID can have different values under these configurations. This means you don't need to create separate color resources for dark and light modes. Instead, you can reference system resources to maintain a consistent look. For example, to set your application's text color, simply use: 54 55 ```ts 56 Text('Use system-defined colors') 57 .fontColor($r('sys.color.ohos_id_color_text_primary')) 58 ``` 59 602. Image Resource Adaptation 61 62 To adapt images to dark and light modes, use resource qualifier directories. Specifically, place images with the same name in the **dark/media** directory. Reference these images using the **$r** syntax based on their **key** values. The system will automatically load the appropriate image based on the current mode. 63 64 For SVG icons, use the [fillColor](arkts-graphics-display.md#displaying-vector-images) attribute with system resources to dynamically adjust their appearance for dark and light modes, eliminating the need for separate image sets. 65 66 ```ts 67 Image($r('app.media.pic_svg')) 68 .width(50) 69 .fillColor($r('sys.color.ohos_id_color_text_primary')) 70 ``` 71 723. Web Component Adaptation 73 74 The **Web** component supports dark color mode configuration. For details, see [Setting the Dark Mode](../web/web-set-dark-mode.md). 75 764. Listening for Color Mode Switching Events 77 78 Applications can listen for system color mode changes and perform custom logic, such as initializing resources of other types. This approach works regardless of whether the application is set to follow the system's dark or light mode. 79 80 a. Save the current color mode to the AppStorage in the **onCreate()** lifecycle of the AbilityStage. 81 82 ```ts 83 onCreate(): void { 84 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 85 AppStorage.setOrCreate('currentColorMode', this.context.config.colorMode); 86 } 87 ``` 88 89 b. Update the color mode to the AppStorage in the **onConfigurationUpdate()** lifecycle callback of the AbilityStage.. 90 91 ```ts 92 onConfigurationUpdate(newConfig: Configuration): void { 93 AppStorage.setOrCreate('currentColorMode', newConfig.colorMode); 94 hilog.info(0x0000, 'testTag', 'the newConfig.colorMode is %{public}s', JSON.stringify(AppStorage.get('currentColorMode')) ?? ''); 95 } 96 ``` 97 98 c. Use @StorageProp and @Watch to listen for color mode changes and refresh the state variable. 99 100 ```ts 101 @StorageProp('currentColorMode') @Watch('onColorModeChange') currentMode: number = ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT; 102 ``` 103 104 d. Refresh the state variable based on the latest color mode in the **aboutToAppear()** API. 105 106 ```ts 107 aboutToAppear(): void { 108 if (this.currentMode == ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT) { 109 // Light mode initialization logic 110 }else { 111 // Dark mode initialization logic 112 } 113 } 114 ``` 115 116 e. Implement the same logic in the @Watch callback function. 117 118 ```ts 119 onColorModeChange(): void { 120 if (this.currentMode == ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT) { 121 // Light mode initialization logic 122 } else { 123 // Dark mode initialization logic 124 } 125 } 126 ``` 127 128## Setting the Application's Color Mode Independently 129 130By default, applications follow the system's color mode. Yet, you can set a fixed mode for your application regardless of the system settings. 131 132```ts 133onCreate(): void { 134 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 135 this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK); 136} 137``` 138 139## Default Judgment Rule 140 1411. If the application calls the **setColorMode** API, its effect takes precedence. 142 1432. If the application does not call the **setColorMode** API: 144 145 - When the application has dark resources in the **dark** directory, built-in components automatically switch to dark mode. 146 147 - When no dark resources are available, built-in components remain in light mode. 148 149  150 151If your application uses built-in components or colors and you want it to switch between dark and light modes along with the system, modify the code as follows to ensure a consistent user experience: 152 153```ts 154onCreate(): void { 155 this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET); 156} 157``` 158
