Mastering Dark Mode in ROMA: A Complete Guide for Mobile Developers

Background

Dark mode reduces blue light in low‑light environments, lessening eye fatigue and saving battery power. As dark mode becomes popular, many users prefer it.

JD Finance App supports dark mode from version 8.0.20, and the ROMA framework fully supports dark‑mode settings. This article details the process of adapting ROMA for dark mode across platforms.

ROMA Configuration and Usage

App dark‑mode settings offer three options: force light mode, force dark mode, or follow the system. Switching to dark mode changes the view smoothly without rebuilding the original view.

1. View Display Mode Setting

ROMA provides a theme-mode attribute for all tags, indicating the current display mode. Three modes are available:

1: force light mode 2: force dark mode 3: follow mode (inherit from parent or system; default is 1 for pages, 3 for tags)

Example code sets theme-mode=3 on a page to follow the window, theme-mode="1" on a div to force light, and leaves a text tag without setting, inheriting theme-mode="3" from its parent.

<template theme-mode=3>
    <div style="align-self: stretch; height: 100px; margin: 10px;" theme-mode="1">
        <text style="color:#000000; font-size: 12px;"> 文本测试 </text>
    </div>
</template>

Using the theme-mode attribute, businesses can flexibly customize view display modes, applying global or node‑specific settings.

2. View Color Setting

Ideally, zero code changes are needed for dark‑mode adaptation if the app relies on a complete color mapping table (light‑mode colors have corresponding dark‑mode values). Designers must follow this mapping when creating UI drafts, allowing automatic color adjustments on mode switches.

The mapping process is illustrated below:

To accommodate complex scenarios, ROMA also provides dark‑mode specific style properties (e.g., background-color-dark, color-dark, src-dark) for UI customization.

<div style="background-color: white; background-color-dark: '#EF4034';">
    <text style="color: '#666666'; color-dark:'#F9F9F9';"> 文本测试 </text>
    <img src="https://img0.baidu.com/it/u=3838093562,4126749835&fm=253&fmt=auto&app=138&f=JPEG?w=1144&h=500">
</div>

View Mode Switching Principle Analysis

ROMA simplifies dark‑mode adaptation with simple configuration, but the underlying process involves many view‑layer changes. The following iOS‑specific analysis shows how system trait changes propagate through the view hierarchy.

1. UITraitEnvironment Protocol Details

The UITraitEnvironment protocol is fundamental in iOS; all views and controllers adopt it to monitor interface environment changes such as dark/light mode, rotation, or size class changes.

@protocol UITraitEnvironment <NSObject>
@property (nonatomic, readonly) UITraitCollection *traitCollection API_AVAILABLE(ios(8.0));
/*! To be overridden as needed to provide custom behavior when the environment's traits change. */
- (void)traitCollectionDidChange:(nullable UITraitCollection *)previousTraitCollection API_DEPRECATED("Use the trait change registration APIs declared in the UITraitChangeObservable protocol", ios(8.0, 17.0), visionos(1.0, 1.0)) API_UNAVAILABLE(watchos);
@end

From iOS 17 onward, UITraitChangeObservable is recommended for finer‑grained trait monitoring.

API_AVAILABLE(ios(17.0), tvos(17.0)) API_UNAVAILABLE(watchos) NS_SWIFT_UI_ACTOR
@protocol UITraitChangeObservable
- (id<UITraitChangeRegistration>)registerForTraitChanges:(NSArray<UITrait> *)traits withHandler:(UITraitChangeHandler)handler;
- (id<UITraitChangeRegistration>)registerForTraitChanges:(NSArray<UITrait> *)traits withTarget:(id)target action:(SEL)action;
- (id<UITraitChangeRegistration>)registerForTraitChanges:(NSArray<UITrait> *)traits withAction:(SEL)action;
- (void)unregisterForTraitChanges:(id<UITraitChangeRegistration>)registration;
@end

2. Impact of System Trait Changes on View Hierarchy

Core iOS classes such as UIScreen, UIWindow, UIViewController, and UIView implement UITraitEnvironment. Trait collections flow from top to bottom:

System traits are provided by UIScreen. UIWindow inherits traits from UIScreen.

The root view controller inherits traits from UIWindow.

Child view controllers inherit from their parent controllers.

Views inherit traits from their view controller.

Subviews inherit traits from their parent view.

Layer objects listen to the corresponding view’s traits to adjust themselves.

The following diagram shows trait value changes when switching from light to dark mode.

3. View Color Setting

For direct color properties like textColor or backgroundColor, use DynamicColors so the view automatically picks the appropriate color when the theme changes.

UIColor* dycolor = [UIColor colorWithDynamicProvider:^UIColor * _Nonnull(UITraitCollection * _Nonnull traitCollection) {
    if ([traitCollection userInterfaceStyle] == UIUserInterfaceStyleLight) {
        return lightResoledColor;
    } else {
        return darkResoledColor ? darkResoledColor : (lightResoledColor ? lightResoledColor : [UIColor clearColor]);
    }
}];
view.backgroundColor = dycolor;

4. Other View Settings

For layer colors, image resources, or Lottie assets, register a theme‑change callback on the view to adjust these resources when the display trait changes.

UIColor* borderColor = jr_themeColorForTrans(_bordercolor_light, _bordercolor_dark);
CAShapeLayer* borderLayer = [[CAShapeLayer alloc] init];
__weak CAShapeLayer* __weakBorderLayer = borderLayer;
[self.view jr_registerForJRThemeChangesWithHandler:^(JRThemeModeStyle style) {
    [CATransaction begin];
    [CATransaction setDisableActions:YES];
    __weakBorderLayer.strokeColor = borderColor.CGColor;
    [CATransaction commit];
} key:@"jr_trans_layer_border_color_key"];

Conclusion

ROMA, as a modern cross‑platform framework, treats dark‑mode adaptation as a comprehensive consideration of user experience, device compatibility, and technology trends. The update provides developers with flexible theme handling and a set of solutions for multi‑theme switching, enabling rapid implementation of high‑quality dark‑mode experiences.