SNumberField <s-number-field>
Một ô nhập số với giá trị tối thiểu, tối đa và bước nhảy tùy chọn. SNumberField là Vue 3 wrapper có type cho web component <s-number-field> của Shopify Polaris.
ts
import { SNumberField } from 'polaris-vue-elements'Best practices
- Chỉ dùng cho giá trị thuần số. Dùng nó cho những thứ như số lượng, số đo hoặc phần trăm. Nếu giá trị có thể chứa chữ cái hoặc ký hiệu, chẳng hạn mã sản phẩm hay số điện thoại, hãy dùng
STextField. - Hiển thị đơn vị. Dùng
prefixhoặcsuffixđể cho biết con số đo cái gì, để người bán không phải đoán mình đang nhập đô la, kilôgam hay phần trăm. - Đặt giới hạn khớp với quy tắc nghiệp vụ. Đặt giá trị
minvàmaxphản ánh đúng những gì được phép, giúp người bán nhập giá trị hợp lệ ngay trước khi gửi form. - Kiểm tra và giải thích lỗi. Kiểm tra mọi giá trị số được nhập, và khi có giá trị không hợp lệ, dùng
errorđể nói chính xác sai ở đâu và cách sửa, thay vì hiển thị một thông báo chung chung.
vue
<SNumberField label="Discount" suffix="%" :min="0" :max="100" />Xem best practices của Shopify cho <s-number-field> (tiếng Anh) để có hướng dẫn đầy đủ.
Ví dụ
Value: 1
vue
<script setup>
import { ref } from 'vue'
import { SNumberField } from 'polaris-vue-elements'
const value = ref('1')
</script>
<template>
<SNumberField label="Quantity" :min="0" :max="100" :step="1" v-model="value" />
<p>Value: {{ value }}</p>
</template>v-model
v-model trên <SNumberField> gắn với property value và lắng nghe DOM event input.
template
<SNumberField v-model="value" />tương đương với:
template
<SNumberField :value="value" @input="value = $event.target.value" />Props
| Prop | Kiểu | Mô tả |
|---|---|---|
autocomplete | "one-time-code" | "cc-number" | "cc-csc" | "on" | "off" | "shipping one-time-code" | "billing one-time-code" | "shipping cc-number" … (3 more) | Gợi ý về nội dung dự kiến của trường. Khi đặt thành on (mặc định), thuộc tính này cho biết trường nên hỗ trợ tự động điền, nhưng bạn không có thêm thông tin ngữ nghĩa nào về nội dung dự kiến. Khi đặt thành off, bạn cho biết trường này chứa thông tin nhạy cảm, hoặc nội dung không bao giờ được lưu, như mã dùng một lần. Ngoài ra, bạn có thể cung cấp giá trị mô tả loại dữ liệu cụ thể mà bạn muốn được nhập vào trường này khi tự động điền. |
defaultValue | string | Giá trị mặc định của trường. |
details | any | Văn bản bổ sung cung cấp ngữ cảnh hoặc hướng dẫn cho trường. Văn bản này được hiển thị cùng với trường và nhãn của nó để cung cấp thêm thông tin hoặc chỉ dẫn cho người dùng. Văn bản này cũng được cung cấp cho người dùng trình đọc màn hình. |
disabled | boolean | Vô hiệu hóa trường, không cho phép bất kỳ tương tác nào. |
error | any | Báo lỗi cho người dùng. Trường sẽ được áp dụng kiểu hiển thị riêng để thông báo các vấn đề cần được giải quyết ngay. |
id | string | Định danh duy nhất của phần tử. |
inputMode | "decimal" | "numeric" | Loại bàn phím ảo hiển thị trên thiết bị di động. - decimal: Hiển thị bàn phím số có dấu thập phân, phù hợp cho giá hoặc số đo. - numeric: Hiển thị bàn phím số không có dấu thập phân, phù hợp cho số nguyên như số lượng. Tìm hiểu thêm về thuộc tính inputmode. |
label | any | Nội dung dùng làm nhãn của trường. |
labelAccessibilityVisibility | "visible" | "exclusive" | Thay đổi khả năng hiển thị của nhãn của component. - visible: nhãn hiển thị với mọi người dùng. - exclusive: nhãn bị ẩn về mặt thị giác nhưng vẫn nằm trong cây trợ năng (accessibility tree). |
max | number | Số thập phân hoặc số nguyên lớn nhất được chấp nhận cho trường. Khi dùng cùng step, giá trị sẽ được làm tròn xuống về số max. Lưu ý: người dùng vẫn có thể dùng bàn phím để nhập số lớn hơn max. Việc thêm kiểm tra hợp lệ phù hợp là trách nhiệm của lập trình viên. |
min | number | Số thập phân hoặc số nguyên nhỏ nhất được chấp nhận cho trường. Khi dùng cùng step, giá trị sẽ được làm tròn lên về số min. Lưu ý: người dùng vẫn có thể dùng bàn phím để nhập số nhỏ hơn min. Việc thêm kiểm tra hợp lệ phù hợp là trách nhiệm của lập trình viên. |
name | string | Định danh cho trường, là duy nhất trong form chứa nó gần nhất. |
placeholder | string | Gợi ý ngắn mô tả giá trị mong đợi của trường. |
prefix | string | Giá trị được hiển thị ngay trước phần có thể chỉnh sửa của trường. Điều này hữu ích để hiển thị một phần ngầm định của giá trị, chẳng hạn "https://" hoặc "+353". Người dùng không thể chỉnh sửa phần này, và nó không được tính vào giá trị của trường. Phần này có thể không hiển thị cho đến khi người dùng tương tác với input. Ví dụ, một nhãn inline có thể chiếm chỗ của prefix cho đến khi người dùng focus vào input. |
readOnly | boolean | Người dùng không thể chỉnh sửa trường. Trường vẫn có thể nhận focus và sẽ được trình đọc màn hình thông báo. |
required | boolean | Trường có bắt buộc phải có giá trị hay không. Yêu cầu này bổ sung giá trị ngữ nghĩa cho trường, nhưng sẽ không tự động hiển thị lỗi. Nếu muốn hiển thị lỗi khi trường này trống, bạn có thể dùng thuộc tính error. |
step | number | Lượng mà giá trị có thể tăng hoặc giảm. Có thể là số nguyên hoặc số thập phân. Nếu max hoặc min được chỉ định cùng với step khi tăng/giảm giá trị qua các nút, giá trị cuối cùng sẽ luôn được làm tròn về max hoặc min thay vì giá trị hợp lệ gần nhất. |
suffix | string | Giá trị được hiển thị ngay sau phần có thể chỉnh sửa của trường. Điều này hữu ích để hiển thị một phần ngầm định của giá trị, chẳng hạn "@shopify.com" hoặc "%". Người dùng không thể chỉnh sửa phần này, và nó không được tính vào giá trị của trường. Phần này có thể không hiển thị cho đến khi người dùng tương tác với input. Ví dụ, một nhãn inline có thể chiếm chỗ của suffix cho đến khi người dùng focus vào input. |
value | string |
Một số cột kiểu ở trên đã được rút gọn cho dễ đọc; union đầy đủ có trong type TypeScript được generate của thư viện (
src/lib/generated/types.ts).
Events
| Event | Kiểu |
|---|---|
blur | FocusEvent |
change | Event |
focus | FocusEvent |
input | Event |
Lắng nghe các event này bằng listener dạng @blur trên <SNumberField>.
Slots
| Slot | Mô tả |
|---|---|
details | |
error |