Các biến global css trong H5 App

Tài liệu này mô tả các Global CSS variables (biến toàn cục) được tự động thêm vào trong Mini App. Các biến này giúp giao diện hiển thị đúng kích thước và không bị che khuất bởi notch (tai thỏ), status bar, hoặc gesture bar của thiết bị.

Giải thích một số khái niệm cơ bản

Thuật ngữ	Giải thích
Notch (tai thỏ)	Là phần lõm hoặc bo tròn trên đầu màn hình (như trên iPhone X trở lên), nơi chứa camera và cảm biến. Nếu không chừa khoảng trống, nội dung có thể bị che khuất.
Status bar	Thanh nhỏ ở đầu màn hình hiển thị các thông tin như giờ, pin, sóng...
Gesture bar (thanh điều hướng)	Thanh mảnh ở cuối màn hình, dùng để vuốt chuyển app, về Home... Nếu không chừa khoảng trống, nút hoặc nội dung có thể nằm đè lên thanh này.
Safe area (vùng an toàn)	Là vùng hiển thị đảm bảo không bị che bởi notch, status bar hoặc gesture bar. Giao diện nên nằm hoàn toàn trong vùng này để hiển thị đẹp trên mọi thiết bị.

Nhóm biến về kích thước thiết bị

Các biến này cung cấp thông tin về kích thước tổng thể và vùng hiển thị của thiết bị, giúp căn chỉnh bố cục giao diện.

Tên biến	Mô tả
--vsf-device-width	Chiều rộng tổng thể của thiết bị (tính cả vùng bo cong hoặc notch).
--vsf-device-height	Chiều cao tổng thể của thiết bị, bao gồm luôn cả status bar và gesture bar.
--vsf-screen-width	Chiều rộng của toàn bộ màn hình hiển thị mà người dùng nhìn thấy.
--vsf-screen-height	Chiều cao của toàn bộ màn hình hiển thị mà người dùng nhìn thấy.
--vsf-window-width	Chiều rộng vùng hiển thị nội dung trong ứng dụng (phần mà web có thể vẽ lên).
--vsf-window-height	Chiều cao vùng hiển thị nội dung trong ứng dụng, không tính các thanh hệ thống bên trên hoặc bên dưới.
--vsf-title-bar-height	Chiều cao của thanh tiêu đề (title bar) - bao gồm --safe-area-inset-top - thường là nơi hiển thị tiêu đề trang hoặc nút quay lại.
--vsf-status-bar-height	Chiều cao của thanh trạng thái (status bar). Biến này giúp chừa khoảng trống phía trên để nội dung không bị đè lên đồng hồ hoặc icon pin.
--vsf-header-padding-right	Khoảng cách trống bên phải của header, để tránh nội dung đè lên nút hệ thống (ví dụ: nút menu hoặc avatar người dùng).
--vsf-header-padding-left	Khoảng cách trống bên trái của header, để tránh nội dung đè lên nút quay lại hoặc logo ứng dụng.

Nhóm biến về vùng an toàn (Safe Area Insets)

Những biến này giúp căn chỉnh giao diện trong vùng hiển thị an toàn, tránh bị che bởi notch hoặc thanh điều hướng.

Tên biến	Mô tả
--safe-area-inset-top	Khoảng cách từ mép trên màn hình đến vùng hiển thị an toàn — giúp chừa chỗ cho notch hoặc status bar.
--safe-area-inset-bottom	Khoảng cách từ mép dưới đến vùng hiển thị an toàn — giúp tránh bị che bởi gesture bar hoặc thanh điều hướng.
--safe-area-inset-left	Khoảng cách an toàn từ mép trái, dùng cho thiết bị có bo cong hoặc notch nằm lệch.
--safe-area-inset-right	Khoảng cách an toàn từ mép phải, tương tự như trên.

Ví dụ cách sử dụng

Dưới đây là ví dụ minh họa cách các biến này giúp giao diện hiển thị chính xác trên thiết bị di động:

const HomePage = () => {
  return (
    <div>
      <div className="header">...</div>
      <div className="page">
        <div className="page__content"></div>
      </div>
    </div>
  )
}

.header {
  height: var(--vsf-title-bar-height);
  padding-top: var(--safe-area-inset-top);
  padding-left: var(--vsf-header-padding-left);
  padding-right: var(--vsf-header-padding-right);
}
.page {
  padding-top: var(--vsf-title-bar-height);
  padding-bottom: var(--safe-area-inset-bottom);
  overflow-y: auto;
}

Kết quả:

• Header sẽ tự động chừa khoảng trống phía trên cho notch.
• Nội dung chính không bị đè lên gesture bar ở dưới.
• Giao diện hiển thị cân đối trên mọi loại điện thoại.

Ngoài ra, bạn có thể sử dụng navigation bar được tích hợp sẵn tại Navigation Bar

// Layout
const MainLayout = () => {
  return (
    <Routes>
      <Route
        path="/"
        element={<HomePage />}
        navigationBar={{
          title: 'Home Page',
          backIcon: false,
        }}
      />
    </Routes>
  )
}

// Page
const HomePage = () => {
  return <Page className="page"></Page>
}