Tệp pages.json đóng vai trò trung tâm trong việc thiết lập các tham số toàn cục cho ứng dụng uni-app. Nó chịu trách nhiệm xác định lộ trình các tệp trang, phong cách cửa sổ, thanh điều hướng gốc và thanh tabbar ở dưới cùng.
Về chức năng, nó chia sẻ điểm tương đồng với phần quản lý trang trong app.json của微信小程序 (WeChat Mini Program). Tuy nhiên, cần lưu ý rằng các yêu cầu quyền như định vị vốn thuộc về app.json trong môi trường gốc, thì trong uni-app sẽ được cấu hình within tệp manifest.
Danh Sách Các Thuộc Tính Cấu Hình
Bảng dưới đây tổng hợp các thuộc tính chính có thể sử dụng trong tệp cấu hình:
| Thuộc tính | Kiểu dữ liệu | Mô tả | Tương thích nền tảng | |
|---|---|---|---|---|
| globalStyle | Object | Không | Thiết lập biểu hiện cửa sổ mặc định cho các trang | - |
| pages | Object Array | Có | Định nghĩa đường dẫn trang và phong cách cửa sổ | - |
| easycom | Object | Không | Quy tắc tự động nhập thành phần | 2.5.5+ |
| tabBar | Object | Không | Cấu hình hiển thị cho thanh tab dưới cùng | - |
| condition | Object | Không | Cấu hình chế độ khởi động | - |
| subPackages | Object Array | Không | Cấu hình tải gói phụ (subpackage) | - |
| preloadRule | Object | Không | Quy tắc tải trước cho gói phụ | WeChat Mini Program |
| workers | String | Không | Thư mục chứa mã Worker |
WeChat Mini Program |
| leftWindow | Object | Không | Cửa sổ bên trái cho màn hình lớn | H5 |
| topWindow | Object | Không | Cửa sổ phía trên cho màn hình lớn | H5 |
| rightWindow | Object | Không | Cửa sổ bên phải cho màn hình lớn | H5 |
| uniIdRouter | Object | Không | Cấu hình liên quan đến chuyển hướng tự động | - |
Dưới đây là một ví dụ minh họa bao gồm hầu hết các tùy chọn cấu hình trong pages.json:
{
"pages": [
{
"path": "views/home/main",
"style": {
"navigationBarTitleText": "Trang Chủ"
}
},
{
"path": "views/services/list",
"style": {
"navigationBarTitleText": "Dịch Vụ"
}
},
{
"path": "views/services/detail",
"style": {
"navigationBarTitleText": "Chi Tiết"
}
}
],
"condition": {
"current": 0,
"list": [
{
"name": "mode_test",
"path": "views/services/detail"
}
]
},
"globalStyle": {
"navigationBarTextStyle": "white",
"navigationBarTitleText": "Ứng Dụng Demo",
"navigationBarBackgroundColor": "#007AFF",
"backgroundColor": "#F5F5F5",
"usingComponents": {
"nav-header": "/components/nav-header"
},
"pageOrientation": "portrait",
"rpxCalcMaxDeviceWidth": 960,
"rpxCalcBaseDeviceWidth": 375
},
"tabBar": {
"color": "#999999",
"selectedColor": "#007AFF",
"borderStyle": "white",
"backgroundColor": "#ffffff",
"list": [
{
"pagePath": "views/home/main",
"iconPath": "static/icons/home.png",
"selectedIconPath": "static/icons/home_active.png",
"text": "Trang Chủ"
},
{
"pagePath": "views/services/list",
"iconPath": "static/icons/service.png",
"selectedIconPath": "static/icons/service_active.png",
"text": "Dịch Vụ"
}
]
},
"easycom": {
"autoscan": true,
"custom": {
"^my-(.*)": "@/components/my-$1.vue"
}
},
"topWindow": {
"path": "layouts/top-bar.vue",
"style": {
"height": "60px"
}
},
"leftWindow": {
"path": "layouts/sidebar.vue",
"style": {
"width": "250px"
}
},
"rightWindow": {
"path": "layouts/info-panel.vue",
"style": {
"width": "300px"
},
"matchMedia": {
"minWidth": 900
}
}
}globalStyle
Phần này dùng để thiết lập thanh trạng thái, thanh điều hướng, tiêu đề và màu nền cửa sổ cho toàn bộ ứng dụng.
| Thuộc tính | Kiểu | Giá trị mặc định | Mô tả | Ghi chú nền tảng |
|---|---|---|---|---|
| navigationBarBackgroundColor | HexColor | #F7F7F7 | Màu nền thanh điều hướng | APP và H5 mặc định là #F7F7F7 |
| navigationBarTextStyle | String | white | Màu tiêu đề thanh điều hướng, chỉ hỗ trợ black/white | Alipay Mini Program không hỗ trợ |
| navigationBarTitleText | String | - | Nội dung văn bản tiêu đề | - |
| navigationStyle | String | default | Phong cách thanh điều hướng (default/custom) | Custom để ẩn thanh gốc |
| backgroundColor | HexColor | #ffffff | Màu nền cửa sổ khi kéo xuống | WeChat Mini Program |
| enablePullDownRefresh | Boolean | false | Bật tính năng kéo để làm mới | - |
| pageOrientation | String | portrait | Cấu hình xoay màn hình (auto/portrait/landscape) | App, WeChat, QQ |
| usingComponents | Object | - | Tham chiếu các thành phần mini program | - |
Lưu ý: Khi sử dụng titleImage trên Alipay Mini Program, bắt buộc phải dùng liên kết https. Thuộc tính maxWidth yêu cầu các phần tử fixed trong trang sử dụng biến css --window-left và --window-right để đảm bảo bố cục.
Cấu Hình Cửa Sổ Responsive (topWindow, leftWindow, rightWindow)
Từ phiên bản uni-app 2.9+, các cấu hình này được thêm vào để giải quyết vấn đề thích ứng màn hình rộng. Bên cạnh cửa sổ chính (mainWindow), bạn có thể thêm các khung hiển thị ở trái, trên hoặc phải.
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
| path | String | Đường dẫn đến trang cấu hình |
| style | Object | Cấu hình hiển thị cửa sổ (width, height...) |
| matchMedia | Object | Quy tắc hiển thị dựa trên kích thước màn hình |
Ví dụ cấu hình matchMedia:
| Thuộc tính | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
| minWidth | Number | 768 | Hiển thị cửa sổ khi độ rộng vùng nhìn thấy >= giá trị này |
Đoạn mã mẫu cho cấu hình cửa sổ:
{
"pages": [
{
"path": "views/auth/login",
"style": {
"topWindow": false,
"leftWindow": false
}
}
],
"rightWindow": {
"path": "layouts/right-panel.vue",
"style": {
"width": "280px"
},
"matchMedia": {
"minWidth": 1024
}
}
}pages
Node pages xác định cấu trúc trang của ứng dụng. Nó nhận một mảng, mỗi phần tử là một đối tượng chứa thông tin về một trang cụ thể.
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
| path | String | Đường dẫn trang (không cần đuôi file) |
| style | Object | Cấu hình window style cho trang này |
Mẹo: Phần tử đầu tiên trong mảng pages được coi là trang khởi động (homepage). Khi thêm hoặc xóa trang, cần cập nhật mảng này.
Ví dụ cấu trúc thư mục:
┌─views
│ ├─home
│ │ └─main.vue
│ └─auth
│ └─login.vue
├─static
├─main.js
└─pages.jsonTương ứng trong pages.json:
{
"pages": [
{
"path": "views/home/main",
"style": { }
},
{
"path": "views/auth/login",
"style": { }
}
]
}style (Cấu hình từng trang)
Các thiết lập trong phần style của từng trang sẽ ghi đè lên các配置 tương tự trong globalStyle.
| Thuộc tính | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
| navigationBarBackgroundColor | HexColor | #000000 | Màu nền thanh điều hướng |
| disableScroll | Boolean | false | Ngăn cuộn trang (chỉ có hiệu lực trong cấu hình trang) |
| navigationBarTitleText | String | - | Tiêu đề trang |
| enablePullDownRefresh | Boolean | false | Bật kéo làm mới |
Ví dụ:
{
"pages": [{
"path": "views/home/main",
"style": {
"navigationBarTitleText": "Tổng Quan",
"enablePullDownRefresh": true
}
}]
}Lưu ý khi tùy chỉnh thanh điều hướng
Khi đặt navigationStyle là custom, thanh điều hướng gốc sẽ ẩn. Trên các thiết bị không phải H5, vùng trạng thái (status bar) có thể bị nội dung trang che khuất. Bạn có thể sử dụng biến css --status-bar-height để tạo khoảng đệm.
<template>
<view>
<view class="status_placeholder"></view>
<view>Nội dung bên dưới </view>
</view>
</template>
<style>
.status_placeholder {
height: var(--status-bar-height);
width: 100%;
}
</style>app-plus (Cấu hình riêng cho App)
Cho phép thiết lập các style đặc thù khi biên dịch sang nền tảng App.
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
| background | HexColor | Màu nền窗体 gốc |
| titleNView | Object | Cấu hình thanh điều hướng |
| pullToRefresh | Object | Cấu hình kéo làm mới |
| softinputMode | String | Chế độ bàn phím (adjustResize/adjustPan) |
titleNView (Thanh điều hướng)
Cung cấp khả năng tùy biến sâu cho thanh điều hướng trên App.
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
| type | String | default/transparent/float |
| buttons | Array | Danh sách nút tùy chỉnh |
| searchInput | Object | Cấu hình ô tìm kiếm |
| backgroundImage | String | Ảnh nền hoặc gradient |
Ví dụ cấu hình titleNView:
{
"pages": [{
"path": "views/news/feed",
"style": {
"app-plus": {
"titleNView": {
"type": "transparent",
"searchInput": {
"placeholder": "Tìm kiếm tin tức",
"backgroundColor": "#ffffff"
},
"buttons": [
{
"text": "Đăng"
}
]
}
}
}
}]
}subNVues (原生子窗体)
Là các窗体 con gốc được nhúng vào trang vue, giúp xử lý các vấn đề về层级 (z-index) và tùy biến giao diện gốc linh hoạt hơn.
{
"pages": [{
"path": "views/map/view",
"style": {
"app-plus": {
"subNVues": [{
"id": "nav_overlay",
"path": "views/map/nav.nvue",
"style": {
"position": "dock",
"height": "50px"
}
}]
}
}
}]
}easycom (Tự động nhập thành phần)
Từ HBuilderX 2.5.5, chế độ easycom cho phép sử dụng component mà không cần import hay đăng ký thủ công, chỉ cần tuân thủ quy tắc đặt tên thư mục.
Ví dụ sử dụng component tự động:
<template>
<view class="box">
<my-list>
<my-list-item title="Mục 1"></my-list-item>
<my-list-item title="Mục 2"></my-list-item>
</my-list>
</view>
</template>
<script>
export default {
data() {
return {}
}
}
</script>Cấu hình tùy chỉnh trong pages.json:
"easycom": {
"autoscan": true,
"custom": {
"^my-(.*)": "@/components/my-$1.vue",
"^lib-(.*)": "package-name/lib-$1.vue"
}
}tabBar (Thanh điều hướng dưới)
Dùng cho các ứng dụng có nhiều tab. Cấu hình này giúp tăng hiệu suất render trên App và Mini Program vì được xử lý bởi engine gốc.
| Thuộc tính | Bắt buộc | Mô tả |
|---|---|---|
| color | Có | Màu chữ mặc định |
| selectedColor | Có | Màu chữ khi chọn |
| backgroundColor | Có | Màu nền thanh tab |
| list | Có | Mảng các tab (tối thiểu 2, tối đa 5) |
| position | Không | bottom hoặc top (top chỉ hỗ trợ WeChat) |
Ví dụ cấu hình tabBar:
"tabBar": {
"color": "#888888",
"selectedColor": "#FF5722",
"backgroundColor": "#FFFFFF",
"list": [{
"pagePath": "views/home/main",
"iconPath": "static/tab/home.png",
"selectedIconPath": "static/tab/home_sel.png",
"text": "Trang Chủ"
}, {
"pagePath": "views/user/profile",
"iconPath": "static/tab/user.png",
"selectedIconPath": "static/tab/user_sel.png",
"text": "Cá Nhân"
}]
}condition (Chế độ khởi động)
Chỉ có hiệu lực trong quá trình phát triển, dùng để mô phỏng việc mở thẳng vào một trang cụ thể (ví dụ: từ link chia sẻ).
"condition": {
"current": 0,
"list": [{
"name": "direct_to_detail",
"path": "views/product/detail",
"query": "id=123&source=share"
}]
}subPackages (Phân chia gói)
Cơ chế分包加载 giúp tối ưu kích thước và tốc độ khởi động cho Mini Program. Gói chính chứa trang khởi động, các gói phụ chứa trang con.
Cấu trúc ví dụ:
┌─views
│ └─index
├─modules
│ ├─shop
│ └─user
└─pages.jsonCấu hình pages.json:
{
"pages": [{
"path": "views/index/home",
"style": {}
}],
"subPackages": [{
"root": "modules/shop",
"pages": [{
"path": "product/list",
"style": {}
}]
}, {
"root": "modules/user",
"pages": [{
"path": "settings/index",
"style": {}
}]
}]
}preloadRule (Quy tắc tải trước)
Cho phép tải trước các gói phụ khi người dùng vào một trang tertentu, giúp chuyển trang nhanh hơn.
"preloadRule": {
"views/index/home": {
"network": "all",
"packages": ["modules/shop"]
}
}Câu Hỏi Thường Gặp (FAQ)
Hỏi: Làm sao để ẩn thanh điều hướng gốc?
Đáp: Đặt navigationStyle thành custom trong phần style của trang hoặc globalStyle. Lưu ý xử lý vùng trạng thái (status bar) thủ công.
Hỏi: Cấu hình quyền định vị ở đâu?
Đáp: Không cấu hình trong pages.json. Hãy sử dụng tệp manifest.json để khai báo các quyền năng cho Mini Program.