--- sourceType: official-guide sourceTypeMatchedRule: fallback slug: MA/zaui/overlay/Modal title: Modal --- ```ts 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 ## Ví dụ ## Bảng thuộc tính ### ModalProps | Tên | Type | Required | Default | Mô tả | | --- | --- | --- | --- | --- | | mask | boolean | No | true | 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ở. | | 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 | true | Cho phép đóng hộp thoại khi click vào mask. | | visible | boolean | No | false | 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. | | 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 | false | Hiển thị các action theo chiều dọc, thay vì mặc định là theo chiều ngang. | | 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 | false | Hiển thị viền phân cách giữa các action. | | 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 | false | 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. | ### ModalActions | Tên | Type | Required | Default | Mô tả | | --- | --- | --- | --- | --- | | text | string | No | | Chữ trên nút | | highLight | boolean | No | false | Hiển thị action dưới dạng nút highlight | | danger | boolean | No | false | Hiển thị action dưới dạng nút danger | | onClick | (e: React.MouseEvent) => void | No | | Callback được gọi khi action được click | | close | boolean | No | false | Nếu được set thành `true`, action sẽ đóng modal khi được click | | disabled | boolean | No | false | Trạng thái hoạt động của action | | key | string | No | | | ### Tiêu chuẩn thiết kế {/* inline-mdx: ../specs/Modal.mdx (from .sources/zmp-docs/zaui-react_versioned_docs/version-1.11.0/overlay/Modal.mdx) */} #### 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 ![Modal light](/assets/MA/img/zaui/modal/modal-light.png) ![Modal dark](/assets/MA/img/zaui/modal/modal-dark.png) --- ##### Anatomy ![Modal Anatomy](/assets/MA/img/zaui/modal/modal-anatomy.png) 1. Container - Required 2. Custom View - Optional - Có thể edit tuỳ ý trong view này 3. Main Items - Required - Include - Title - Description ![Modal main items](/assets/MA/img/zaui/modal/modal-main-content.png) ![Modal title](/assets/MA/img/zaui/modal/modal-title.png) ![Modal description](/assets/MA/img/zaui/modal/modal-desc.png) 4. Add-on Items - Optional - Can be these items ![Modal Add-on](/assets/MA/img/zaui/modal/add-on.png) 5. Divider - Required 6. Action - 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 7. 7. Dim Background - Required ##### Specs Max height of dialog = 80% screen height ![Overal](/assets/MA/img/zaui/modal/specs-overal.png) ![Content](/assets/MA/img/zaui/modal/specs-content.png) ![Actions](/assets/MA/img/zaui/modal/specs-actions.png) --- ##### 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 ![Modal Focus Input](/assets/MA/img/zaui/modal/modal-input-focus-1.png) **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 ![Modal Focus Input](/assets/MA/img/zaui/modal/modal-input-focus-2.png) **Đ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 ![Modal Normal](/assets/MA/img/zaui/modal/modal-normal.png) ![Modal Normal](/assets/MA/img/zaui/modal/modal-normal-2.png) ![Modal Normal](/assets/MA/img/zaui/modal/modal-normal-3.png) **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 ![Danger](/assets/MA/img/zaui/modal/modal-danger-1.png) ![Danger](/assets/MA/img/zaui/modal/modal-danger-2.png) ![Dabger](/assets/MA/img/zaui/modal/modal-danger-3.png) **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 ![With Input](/assets/MA/img/zaui/modal/modal-input.png) ![With Input](/assets/MA/img/zaui/modal/modal-input-2.png) #### 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 ![Promotion modal](/assets/MA/img/zaui/modal/pr-modal-1.png) ![Promotion modal](/assets/MA/img/zaui/modal/pr-modal-1-dark.png) ![Promotion modal](/assets/MA/img/zaui/modal/pr-modal-2.png) ![Promotion modal](/assets/MA/img/zaui/modal/pr-modal-2-dark.png) ![Promotion modal](/assets/MA/img/zaui/modal/pr-modal-3.png) ![Promotion modal](/assets/MA/img/zaui/modal/pr-modal-3-dark.png) --- ##### Anatomy ![Promotion modal specs](/assets/MA/img/zaui/modal/pr-modal-specs.png) 5. Container - Required 6. Content View - Required 7. Action - Required - Hiển thị - Default: 1 primary button (blue) - Optional: thêm tối đa 1 secondary button 8. Dim Background - Required **Content View** Gồm 2 phần: - Content Page - Page Indicator ![Promotion modal content view](/assets/MA/img/zaui/modal/pr-modal-content-view.png) 1. Content Page - Required - Gồm 2 loại: - 1. Custom (vertical tự custom content) - 2. Default ![Promotion modal content view](/assets/MA/img/zaui/modal/pr-modal-content-default.png) 1. Image View - Required 2. Title - Required - Không limit số dòng - Font-size: h-normal ![Promotion modal content view](/assets/MA/img/zaui/modal/pr-modal-title.png) 3. Description - 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 ![Promotion modal content view](/assets/MA/img/zaui/modal/pr-modal-desc.png) 2. Page 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** ![Specs](/assets/MA/img/zaui/modal/pr-modal-specs.png) ![Specs](/assets/MA/img/zaui/modal/pr-modal-specs-content.png) **Content Page** **1. Custom (Vertical tự custom)** Recommended spacing specs ![Specs](/assets/MA/img/zaui/modal/pr-modal-specs-custom.png) **2. Default** ![Specs](/assets/MA/img/zaui/modal/pr-modal-specs-default.png) Actions ![actions](/assets/MA/img/zaui/modal/pr-modal-specs-actions.png) --- ##### 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 ![Scrollbar](/assets/MA/img/zaui/modal/pr-modal-scrollbar.png) --- ##### Usage **Transparent background** ![Transparent Background](/assets/MA/img/zaui/modal/usage-transparent-bg-1.png) ![Transparent Background](/assets/MA/img/zaui/modal/usage-transparent-bg-2.png) **Filled background** ![Filled Background](/assets/MA/img/zaui/modal/usage-filled-bg-1.png) ![Filled Background](/assets/MA/img/zaui/modal/usage-filled-bg-2.png) {/* inline-mdx: end ../specs/Modal.mdx */}