RcSwitch Core Architecture & Type System: HarmonyOS 6 ComponentV2 Deep Dive

Overall Architecture Design

1. Dual-File Separation Architecture

RcSwitch adopts a dual-file separation architecture consistent with RcRadio and RcCheckbox: index.ets: Component body containing rendering logic, event handling, and computed methods. index.type.ets: Type definitions with all externally exposed types centrally managed.

This separation achieves concern isolation : consumers can import only the type file for TypeScript type checking without loading the full component implementation, reducing unnecessary dependency propagation in large projects.

2. ComponentV2 Decorator System

RcSwitch uses @ComponentV2, HarmonyOS 6's new component decorator system. Key differences from legacy @Component appear in state management:

@ComponentV2
export struct RcSwitch {
  @Param @Require switchModelValue: RcSwitchValue = false
  @Param onSwitchModelValueChange: (value: RcSwitchValue) => void = () => {}
  @Local rcSwitchInnerValue: RcSwitchValue = false
  @Local rcSwitchInnerLoading: boolean = false
}

@Param

: Declares input parameters from parent components, equivalent to legacy @Prop, supporting unidirectional data flow. @Param @Require: Marks a parameter as required; compile-time error if omitted, adding a runtime constraint. @Local: Declares internal private state not exposed externally, similar to legacy @State.

Note: @Param differs from legacy @Prop by explicitly expressing "this is an externally passed parameter" semantics rather than "state I maintain myself," allowing immediate distinction of data sources when reading component code.

3. Controlled Mode Two-Way Binding Design

RcSwitch implements two-way binding via a parameter pair — switchModelValue receives external state, onSwitchModelValueChange notifies external updates:

// Parent component side
@State myValue: RcSwitchValue = false

RcSwitch({
  switchModelValue: this.myValue,
  onSwitchModelValueChange: (value: RcSwitchValue) => {
    this.myValue = value
  }
})

This is an explicit controlled mode , semantically aligned with Vue's v-model. Internally, rcSwitchInnerValue serves as the rendering basis; external switchModelValue acts only as initial value and sync source, kept consistent via lifecycle hooks.

Type System Design

1. RcSwitchValue Union Type

export type RcSwitchValue = boolean | string | number

RcSwitchValue

is the core type design, allowing three primitive types as the switch's "active" and "inactive" values, breaking the traditional true/false limitation. Use cases:

Standard toggle : activeValue: true, inactiveValue: false — default behavior, directly expresses boolean semantics.

API fields : activeValue: '100', inactiveValue: '0' — backend fields as strings, no conversion needed.

Enum values : activeValue: 1, inactiveValue: 0 — numeric enums common in config APIs.

Benefit: decouples state values from display logic , letting parent components bind raw API responses directly without external type conversion.

2. RcSwitchSize Size Type

export type RcSwitchSize = 'small' | 'default' | 'large'

Three semantic size tiers. In parameter declaration, the size type extends to:

@Param switchSize: RcSwitchSize | RcStringNumber = 'default'

RcStringNumber

(global string | number) allows developers to pass exact numeric values (e.g., 30) or numeric strings (e.g., '30') for precise size control, greatly increasing flexibility.

3. RcSwitchInlinePosition Inline Position Type

export type RcSwitchInlinePosition = 'none' | 'inline'

Controls text/icon display position strategy: 'none': Text/icon rendered outside switch on both sides (switches left/right with active state). 'inline': Text/icon embedded inside the thumb.

The two modes use completely different rendering branches: 'none' uses external Builder rendering, 'inline' uses internal Stack overlay rendering (detailed in follow-up articles).

Internal State & Lifecycle Synchronization

1. Two-Level State Mechanism

RcSwitch runs two state layers:

External (controlled layer): switchModelValue ──init/sync──> rcSwitchInnerValue (render layer)
                                                          |
                                                          renders

External switchModelValue does not drive rendering directly; it syncs to internal rcSwitchInnerValue, which triggers UI refresh. This enables async control mode : temporarily withhold rcSwitchInnerValue updates to achieve "click freezes UI, wait for async result then update" behavior.

2. Lifecycle Sync Strategy

aboutToAppear(): void {
  this.rcSwitchInnerValue = this.switchModelValue
}

aboutToRecycle(): void {
  if (this.switchModelValue !== this.rcSwitchInnerValue) {
    this.rcSwitchInnerValue = this.switchModelValue
  }
}

aboutToAppear

: On initial mount, sync external value to internal for initialization. aboutToRecycle: On component recycle (reuse), check once to prevent state corruption in list reuse scenarios.

The inequality check ( !==) in aboutToRecycle is a key performance guard : sync only when external and internal values truly differ, avoiding meaningless state updates and UI repaints.

3. rcSwitchIsActive Computed Property

private get rcSwitchIsActive(): boolean {
  return this.rcSwitchInnerValue === this.switchActiveValue
}

This private getter centralizes activation judgment; all rendering logic (background color, thumb position, text content) depends on it rather than direct value comparison. Significance: when switchActiveValue is customized to non- true (e.g., string '100'), the entire component works correctly without any other changes.

Parameter Overview

1. High-Frequency Parameters

switchModelValue

( RcSwitchValue, required) — Current bound value. onSwitchModelValueChange ( Function, default () => {}) — Value change callback (two-way binding). switchDisabled ( boolean, default false) — Whether disabled. switchLoading ( boolean, default false) — Whether loading. switchSize ( RcSwitchSize | RcStringNumber, default 'default') — Switch size. switchActiveColor ( string | Resource, default '#409EFF') — Active background color. switchInactiveColor ( string | Resource, default '#DCDFE6') — Inactive background color.

2. Extended Parameters

switchActiveValue

( RcSwitchValue, default true) — Value when active. switchInactiveValue ( RcSwitchValue, default false) — Value when inactive. switchAsyncChange ( boolean, default false) — Enable async control mode. switchBeforeChange ( Function | null, default null) — Pre-change hook. switchInlinePrompt ( RcSwitchInlinePosition, default 'none') — Inline prompt mode. switchSpace ( RcStringNumber, default 2) — Thumb-to-border spacing. switchWidth ( RcStringNumber, default 0) — Custom switch width.

Summary

RcSwitch's core architecture embodies three design principles: type safety (union types enable multi-value scenarios), explicit controlled (clear two-way binding semantics), and state layering (external params isolated from internal render state). Understanding this architecture is the foundation for leveraging RcSwitch's advanced features; follow-up articles will detail size system, color states, event system, and other implementation specifics.