STextField <s-text-field>
Một ô nhập văn bản một dòng với nhãn, placeholder, lỗi xác thực và văn bản trợ giúp. STextField là Vue 3 wrapper có type cho web component <s-text-field> của Shopify Polaris.
ts
import { STextField } from 'polaris-vue-elements'Best practices
- Làm rõ dữ liệu cần nhập. Viết
labelvàplaceholdercho người bán biết cần nhập gì và theo định dạng nào. Câu chữ mơ hồ dẫn đến phải đoán, lỗi xác thực và sự khó chịu. - Thêm ngữ cảnh bằng prefix hoặc suffix. Dùng
prefixvàsuffixđể thể hiện loại giá trị và định dạng của nó, ví dụ người bán nên gõ cả URL hay chỉ subdomain, hoặc giá đầy đủ hay chỉ số tiền. - Dựa ràng buộc trên yêu cầu thực. Đặt
minLength,maxLengthvà các quy tắc xác thực theo nhu cầu nghiệp vụ thực tế thay vì những con số tùy tiện, và cho người bán biết chúng là gì. - Phản hồi sớm và cụ thể. Cho người bán biết dữ liệu nhập có hợp lệ hay không ngay khi họ gõ, không chỉ khi gửi. Khi không hợp lệ, dùng
errorđể giải thích sai ở đâu và cách sửa.
vue
<STextField label="Store address" prefix="https://" suffix=".myshopify.com" />Xem best practices của Shopify cho <s-text-field> (tiếng Anh) để có hướng dẫn đầy đủ.
Ví dụ
Value: (empty)
vue
<script setup>
import { ref } from 'vue'
import { STextField } from 'polaris-vue-elements'
const value = ref('')
</script>
<template>
<STextField label="Your name" placeholder="Jane Doe" v-model="value" />
<p>Value: {{ value }}</p>
</template>v-model
v-model trên <STextField> gắn với property value và lắng nghe DOM event input.
template
<STextField v-model="value" />tương đương với:
template
<STextField :value="value" @input="value = $event.target.value" />Props
| Prop | Kiểu | Mô tả |
|---|---|---|
autocomplete | "language" | "organization" | "name" | "additional-name" | "address-level1" | "address-level2" | "address-level3" | "address-level4" … (84 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. |
icon | "cart-filled" | "channels-filled" | "home-filled" | "order-filled" | "person-filled" | "product-filled" | "color" | "info" … (597 more) | Loại icon hiển thị trong trường. |
id | string | Định danh duy nhất của phần tử. |
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). |
maxLength | number | Chỉ định số ký tự tối đa được phép. |
minLength | number | Chỉ định số ký tự tối thiểu được phép. |
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. |
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 | Giá trị hiện tại của trường. Nếu bỏ qua, trường sẽ trống. |
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 <STextField>.
Slots
| Slot | Mô tả |
|---|---|
accessory | Nội dung bổ sung hiển thị bên cạnh text field, thường là một icon hoặc nút cung cấp chức năng liên quan như mở tooltip trợ giúp hoặc kích hoạt một modal. |
details | |
error |