Modal
import { Modal } from "zmp-ui";
Dùng để hiển thị nội dung quan trọng hoặc yêu cầu người dùng thực hiện một hành động cụ thể trước khi tiếp tục sử dụng tính năng của ứng dụng.
- Hướng dẫn sử dụng
- Tiêu chuẩn thiết kế
Ví dụ
Bảng thuộc tính
ModalProps
| Property | Type | Required | Description |
|---|---|---|---|
| mask | boolean | No | Mask là một lớp overlay màu xám được phủ lên các thành phần bên dưới hộp thoại, ngăn không cho người dùng tương tác với các nội dung đó và tập trung vào hộp thoại được mở. (default: true) |
| afterClose | () => void | No | Callback được gọi sau khi hộp thoại đóng |
| onClose | (e: React.SyntheticEvent) => void | No | Callback được gọi khi người dùng yêu cầu đóng hộp thoại. Cần phải cập nhật lại giá trị của `visible` nếu truyền vào. |
| maskClosable | boolean | No | Cho phép đóng hộp thoại khi click vào mask. (default: true) |
| visible | boolean | No | Trạng thái hiển thị của hộp thoại. Cần được sử dụng chung với `onClose` để cập nhật lại giá trị của `visible` khi người dùng yêu cầu đóng hộp thoại. (default: false) |
| title | string | No | Tiêu đề của hộp thoại, được hiển thị ở phía trên cùng của hộp thoại. |
| coverSrc | string | No | Đường dẫn đến hình ảnh cover của hộp thoại |
| modalStyle | React.CSSProperties | No | Inline style cho hộp thoại |
| maskStyle | React.CSSProperties | No | Inline style cho mask |
| modalClassName | string | No | CSS class cho modal |
| maskClassName | string | No | CSS class cho mask |
| width | string | number | No | Độ rộng của hộp thoại. Nếu không được thiết lập, modal sẽ có độ rộng mặc định theo độ rộng của nội dung và chiều rộng của màn hình. |
| height | string | number | No | Chiều cao của hộp thoại. Nếu không được thiết lập, modal sẽ có chiều cao mặc định theo chiều cao của nội dung và chiều cao của màn hình. |
| description | string | No | Nội dung của hộp thoại, được hiển thị phía dưới tiêu đề. Nếu nội dung cần hiển thị không phải là text, sử dụng `children` để truyền ReactNode vào thay vì `description`. |
| actions | ModalActions[] | No | Mảng thiết lập các nút để người dùng thực hiện các hành động trên hộp thoại. |
| verticalActions | boolean | No | Hiển thị các action theo chiều dọc, thay vì mặc định là theo chiều ngang. (default: false) |
| children | React.ReactNode | No | Nội dung của hộp thoại, được hiển thị ở dưới description và trên các action. |
| actionsDivider | boolean | No | Hiển thị viền phân cách giữa các action. (default: false) |
| zIndex | number | No | Độ sâu của hộp thoại, dùng để xác định thứ tự hiển thị của hộp thoại trong trường hợp có nhiều modal được mở cùng lúc. |
| unmountOnClose | boolean | No | Mặc định khi người dùng đóng hộp thoại, modal vẫn còn được render trong DOM và chỉ bị ẩn đi. Thiết lập này cho phép gỡ hộp thoại khỏi cây DOM hoàn toàn sau khi đóng.
Thiết lập này có thể giúp giảm bộ nhớ được sử dụng trong trường hợp hộp thoại có nội dung lớn. Tuy nhiên, khi hộp thoại được mở lại, nội dung của hộp thoại sẽ được render lại từ đầu. Phù hợp với những hộp thoại chỉ sử dụng một lần. (default: false) |
ModalActions
| Property | Type | Required | Description |
|---|---|---|---|
| text | string | No | Chữ trên nút |
| highLight | boolean | No | Hiển thị action dưới dạng nút highlight (default: false) |
| danger | boolean | No | Hiển thị action dưới dạng nút danger (default: false) |
| onClick | (e: React.MouseEvent) => void | No | Callback được gọi khi action được click |
| close | boolean | No | Nếu được set thành `true`, action sẽ đóng modal khi được click (default: false) |
| disabled | boolean | No | Trạng thái hoạt động của action (default: false) |
| key | string | No |
1. Information Dialog
Hộp thoại:
- Yêu cầu user xác minh xem họ muốn tiếp tục hay hủy thao tác
- Hiển thị thông tin user cần được biết
Hộp thoại cùng với dim background chen ngang trước khi hệ thống thực hiện lệnh của user
Note: Max number of stacking modals = 2
Components
Anatomy
- 1Container
- Required
- 2Custom View
- Optional
- Có thể edit tuỳ ý trong view này
- 3Main Items
- Required
- Include
- Title
- Description
- 4Add-on Items
- Optional
- Can be these items
- 5Divider
- Required
- 6Action
- Required
- Hiển thị:
- Default: 1 primary action (blue or red)
- Optional: thêm tối đa 2 secondary actions
- Vị trí:
- Default: horizontal
- Trường hợp text dài, chiều ngang không đủ hiện -> đổi sang dạng vertical
- 77. Dim Background
- Required
Specs
Max height of dialog = 80% screen height
Behavior
Dismiss
User có thể tắt Modal bằng cách
- Tap out to dismiss (tapOutsideToDismiss)
- Có thể ON/OFF
- Default = ON
- Tap dismissive button (bên ngoài truyền vào)
Focused Text Input with keyboard
Trường hợp 1 Modal được đẩy lên trên keyboard
- Modal cách keyboard 16px
Trường hợp 2 Modal được đẩy lên đã chạm status bar nhưng không đủ chỗ đẩy full modal
- Vùng Content thành Scrollview
- Focused Text Input cách keyboard 32px
Điều kiện đóng keyboard
Thoả 1 trong các điều kiện sau:
- Khi user bấm vào bất kì vùng nào trong InformationDialog, ngoài các InputField
- Khi user dismiss InformationDialog
*Khi user scroll trong InformationDialog, không đóng keyboard.
Usage
Confirmation Dialog
Normal
Dialog xuất hiện sau khi user chọn hành động bất kì cần được confirm trước khi hành động được thực hiện
Danger
Dialog xuất hiện sau khi user chọn hành động mang tính destructive (Xóa, Thoát, Thu hồi, Đăng xuất,...) cần được confirm trước khi hành động được thực hiện
Text Input
Dialog xuất hiện sau khi user chọn hành động mà sau đó cần nhập thông tin để tiếp tục quá trình thực hiện hành động
2. Promotion Popup
- Hộp thoại được sử dụng cho mục đích promote, introduce, onboarding cho tính năng mới
- Nên được sử dụng đúng context vì mức độ interruption rất lớn
Components
Anatomy
- 5Container
- Required
- 6Content View
- Required
- 7Action
- Required
- Hiển thị
- Default: 1 primary button (blue)
- Optional: thêm tối đa 1 secondary button
- 8Dim Background
- Required
Content View
Gồm 2 phần:
- Content Page
- Page Indicator
- 1Content Page
- Required
- Gồm 2 loại:
- 1. Custom (vertical tự custom content)
- 2. Default
- 1Image View
- Required
- 2Title
- Required
- Không limit số dòng
- Font-size: h-normal
- 3Description
- Required
- Number of text rows
- Design: maximum 3 rows
- 1 text row: do not use icon
- 2 - 3 text rows: use icon as bullet point
- Dev: can add multiple
- Font-size: t-normal
- 2Page Indicator
- Sử dụng khi có từ 2 content page trở lên được truyền vào
Specs
Max height of dialog = 80% screen height
Content Page
1. Custom (Vertical tự custom)
Recommended spacing specs
2. Default
Actions
Behavior
Behavior
User có thể tắt Modal bằng cách
- Tap out to dismiss (maskClosable)
- Có thể ON/OFF
- Default = OFF
- Bấm dismissive button (bên ngoài truyền vào)
Scroll
Khi Modal chứa content vượt quá max height, cần hiển thị scrollbar. Animation: dùng ScrollView của native
Scrollbar Specs
Usage
Transparent background
Filled background
