feat(NumberField): support readonly for the NumberField (#2016)

kricsleo · web-flow · commit 987f42a127ba · 2025-07-11T14:36:02.000+08:00
* feat(NumberField): support `readonly` for the `NumberField`

* docs(NumberField): add `readonly`
diff --git a/docs/content/meta/NumberFieldRoot.md b/docs/content/meta/NumberFieldRoot.md
@@ -80,6 +80,12 @@
     'type': 'string',
     'required': false
   },
+  {
+    'name': 'readonly',
+    'description': '<p>When <code>true</code>, the Number Field is read-only.</p>\n',
+    'type': 'boolean',
+    'required': false
+  },
   {
     'name': 'required',
     'description': '<p>When <code>true</code>, indicates that the user must set the value before the owning form can be submitted.</p>\n',
diff --git a/packages/core/src/NumberField/NumberField.test.ts b/packages/core/src/NumberField/NumberField.test.ts
@@ -119,6 +119,28 @@ describe('numberField', () => {
     expect(input.value).toBe('0')
   })
 
+  it('should not be changed when readonly', async () => {
+    const { root, input, increment, decrement } = setup({ defaultValue: 0, readonly: true })
+
+    expect(root.getAttribute('data-readonly')).toBe('')
+    expect(input.getAttribute('data-readonly')).toBe('')
+    await fireEvent.keyDown(input, { key: kbd.ARROW_UP })
+    expect(input.value).toBe('0')
+    await fireEvent.keyDown(input, { key: kbd.ARROW_DOWN })
+    expect(input.value).toBe('0')
+    await userEvent.click(increment)
+    expect(input.value).toBe('0')
+    await userEvent.click(decrement)
+    expect(input.value).toBe('0')
+  })
+
+  it('should be be focusable when readonly', async () => {
+    const { input } = setup({ defaultValue: 0, readonly: true })
+
+    await userEvent.tab()
+    expect(input).toBe(document.activeElement)
+  })
+
   describe('with disable wheel change option', () => {
     it('should update value when scroll by default', async () => {
       const { input } = setup({
diff --git a/packages/core/src/NumberField/NumberFieldDecrement.vue b/packages/core/src/NumberField/NumberFieldDecrement.vue
@@ -17,7 +17,7 @@ const props = withDefaults(defineProps<NumberFieldDecrementProps>(), {
 })
 
 const rootContext = injectNumberFieldRootContext()
-const isDisabled = computed(() => rootContext.disabled?.value || props.disabled || rootContext.isDecreaseDisabled.value)
+const isDisabled = computed(() => rootContext.disabled?.value || rootContext.readonly.value || props.disabled || rootContext.isDecreaseDisabled.value)
 
 const { primitiveElement, currentElement } = usePrimitiveElement()
 const { isPressed, onTrigger } = usePressedHold({ target: currentElement, disabled: isDisabled })
diff --git a/packages/core/src/NumberField/NumberFieldIncrement.vue b/packages/core/src/NumberField/NumberFieldIncrement.vue
@@ -17,7 +17,7 @@ const props = withDefaults(defineProps<NumberFieldIncrementProps>(), {
 })
 
 const rootContext = injectNumberFieldRootContext()
-const isDisabled = computed(() => rootContext.disabled?.value || props.disabled || rootContext.isIncreaseDisabled.value)
+const isDisabled = computed(() => rootContext.disabled?.value || rootContext.readonly.value || props.disabled || rootContext.isIncreaseDisabled.value)
 
 const { primitiveElement, currentElement } = usePrimitiveElement()
 const { isPressed, onTrigger } = usePressedHold({ target: currentElement, disabled: isDisabled })
diff --git a/packages/core/src/NumberField/NumberFieldInput.vue b/packages/core/src/NumberField/NumberFieldInput.vue
@@ -68,6 +68,8 @@ function handleChange() {
     :inputmode="rootContext.inputMode.value"
     :disabled="rootContext.disabled.value ? '' : undefined"
     :data-disabled="rootContext.disabled.value ? '' : undefined"
+    :readonly="rootContext.readonly.value ? '' : undefined"
+    :data-readonly="rootContext.readonly.value ? '' : undefined"
     autocomplete="off"
     autocorrect="off"
     spellcheck="false"
diff --git a/packages/core/src/NumberField/NumberFieldRoot.vue b/packages/core/src/NumberField/NumberFieldRoot.vue
@@ -23,6 +23,8 @@ export interface NumberFieldRootProps extends PrimitiveProps, FormFieldProps {
   locale?: string
   /** When `true`, prevents the user from interacting with the Number Field. */
   disabled?: boolean
+  /** When `true`, the Number Field is read-only. */
+  readonly?: boolean
   /** When `true`, prevents the value from changing on wheel scroll. */
   disableWheelChange?: boolean
   /** When `true`, inverts the direction of the wheel change. */
@@ -47,6 +49,7 @@ interface NumberFieldRootContext {
   validate: (val: string) => boolean
   applyInputValue: (val: string) => void
   disabled: Ref<boolean>
+  readonly: Ref<boolean>
   disableWheelChange: Ref<boolean>
   invertWheelChange: Ref<boolean>
   max: Ref<number | undefined>
@@ -75,7 +78,7 @@ const props = withDefaults(defineProps<NumberFieldRootProps>(), {
   stepSnapping: true,
 })
 const emits = defineEmits<NumberFieldRootEmits>()
-const { disabled, disableWheelChange, invertWheelChange, min, max, step, stepSnapping, formatOptions, id, locale: propLocale } = toRefs(props)
+const { disabled, readonly, disableWheelChange, invertWheelChange, min, max, step, stepSnapping, formatOptions, id, locale: propLocale } = toRefs(props)
 
 const modelValue = useVModel(props, 'modelValue', emits, {
   defaultValue: props.defaultValue,
@@ -107,9 +110,9 @@ const isIncreaseDisabled = computed(() => (
 
 function handleChangingValue(type: 'increase' | 'decrease', multiplier = 1) {
   inputEl.value?.focus()
-  const currentInputValue = numberParser.parse(inputEl.value?.value ?? '')
-  if (props.disabled)
+  if (props.disabled || props.readonly)
     return
+  const currentInputValue = numberParser.parse(inputEl.value?.value ?? '')
   if (isNaN(currentInputValue)) {
     modelValue.value = min.value ?? 0
   }
@@ -200,6 +203,7 @@ provideNumberFieldRootContext({
   validate,
   applyInputValue,
   disabled,
+  readonly,
   disableWheelChange,
   invertWheelChange,
   max,
@@ -218,6 +222,7 @@ provideNumberFieldRootContext({
     :as="as"
     :as-child="asChild"
     :data-disabled="disabled ? '' : undefined"
+    :data-readonly="readonly ? '' : undefined"
   >
     <slot
       :model-value="modelValue"
@@ -230,6 +235,7 @@ provideNumberFieldRootContext({
       :value="modelValue"
       :name="name"
       :disabled="disabled"
+      :readonly="readonly"
       :required="required"
     />
   </Primitive>
