ArkUI TextInput Read-Only Patterns for HarmonyOS: enabled(false), focusOnTouch(false), focusable(false)

#harmonyos #arkui #textinput #readonlytextinput

Read the original article：ArkUI TextInput Read-Only Patterns for HarmonyOS: enabled(false), focusOnTouch(false), focusable(false)

ArkUI TextInput Read-Only Patterns for HarmonyOS: `enabled(false)`, `focusOnTouch(false)`, `focusable(false)`

Requirement Description

Prevent users from editing the content of a TextInput while keeping the UI behavior and look appropriate for HarmonyOS (including wearables).

Background Knowledge

enabled(boolean) — common attribute to control whether a component is interactive. When set to false, the system applies a disabled (grayscale) style. (Docs)
focusOnTouch(boolean) — controls whether the component can gain focus via tap; useful for tap-to-focus components like TextInput. (Docs)
focusable(boolean) — general focus capability toggle for most components. When false, the component cannot obtain focus. (Docs)

Implementation Steps

Choose one of the following based on your UX requirements:

Disable interaction and show disabled style
Use .enabled(false) when you want the control to be clearly non-interactive and allow the system’s disabled styling.
Block tap-to-focus but keep normal visual
Use .focusOnTouch(false) to prevent the keyboard/focus while preserving the normal (non-disabled) appearance.
Completely remove focusability
Use .focusable(false) for a general, comprehensive way to block focus from any source.

Code Snippet / Configuration

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Column({ space: 16 }) {
      // Option 1: Disabled look + no interaction
      TextInput({ text: this.message })
        .enabled(false)
        .fontColor(Color.Blue)

      // Option 2: No tap-to-focus, keeps normal visual
      TextInput({ text: this.message })
        .focusOnTouch(false)
        .fontColor(Color.Gray)

      // Option 3: Not focusable at all
      TextInput({ text: this.message })
        .focusable(false)
        .fontColor(Color.Brown)
    }
    .padding(10)
  }
}

Test Results

Verified on API Version 19 Release with HarmonyOS 5.1.1 Release SDK in DevEco Studio 5.1.1 Release: editing is blocked in all three options; visuals differ as described.

Limitations or Considerations

.enabled(false) changes the control’s appearance (disabled/grayscale). If you must keep the normal look, prefer .focusOnTouch(false) or .focusable(false).
If text is rarely edited, consider rendering with Text for read-only display and switching to TextInput only when an explicit “Edit” action is triggered.
Wearables: to avoid accidental keyboard/focus on small screens, defaulting to .focusOnTouch(false) (or .focusable(false)) is often the best UX.

DEV Community