uni-app開發指南

繁體中文

简体中文
English

繁體中文

简体中文
English

主題

uni-app 專案結構詳解 ​

本文將詳細介紹 uni-app 專案的檔案結構，幫助您更好地理解和組織專案程式碼。

概述 ​

uni-app 專案結構遵循 Vue.js 規範，同時具有自己的特殊檔案和目錄。理解專案結構是開發 uni-app 應用的基礎。

基本專案結構 ​

my-uni-app/
├── uniCloud/                   # 雲開發目錄（可選）
│   ├── cloudfunctions/         # 雲函數目錄
│   └── database/               # 資料庫目錄
├── components/                 # 元件目錄
│   └── comp-a.vue             # 可複用元件
├── pages/                      # 頁面目錄
│   ├── index/
│   │   └── index.vue          # 首頁
│   └── list/
│       └── list.vue           # 列表頁
├── static/                     # 靜態資源目錄
│   ├── images/                # 圖片資源
│   └── fonts/                 # 字型資源
├── uni_modules/               # uni_module 外掛目錄
├── store/                     # 狀態管理目錄（可選）
├── api/                       # API 介面目錄（可選）
├── utils/                     # 工具函數目錄（可選）
├── main.js                    # Vue 初始化入口檔案
├── App.vue                    # 應用配置檔案
├── manifest.json              # 應用配置清單
├── pages.json                 # 頁面路由配置
├── uni.scss                   # 全域樣式變數（可選）
└── package.json               # 專案依賴配置

提示：uni-app 專案結構遵循 Vue 規範，同時也有自己的特殊檔案。

核心檔案詳解 ​

1. pages.json - 頁面路由配置 ​

pages.json 檔案用來對 uni-app 進行全域配置，決定頁面檔案的路徑、視窗樣式、原生的導航欄、底部的原生 tabbar 等。

基本結構 ​

json
{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首頁"
      }
    },
    {
      "path": "pages/list/list",
      "style": {
        "navigationBarTitleText": "列表頁"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "static/tabbar/home.png",
        "selectedIconPath": "static/tabbar/home-active.png",
        "text": "首頁"
      },
      {
        "pagePath": "pages/list/list",
        "iconPath": "static/tabbar/list.png",
        "selectedIconPath": "static/tabbar/list-active.png",
        "text": "列表"
      }
    ]
  }
}

主要配置項 ​

  • pages：頁面路徑陣列，第一個頁面為首頁
  • globalStyle：全域視窗樣式配置
  • tabBar：底部標籤欄配置
  • condition：啟動模式配置
  • subPackages：分包配置

2. manifest.json - 應用配置清單 ​

manifest.json 檔案是應用的配置檔案，用於指定應用的名稱、圖示、許可權等資訊。

基本結構 ​

json
{
  "name": "我的uni-app",
  "appid": "__UNI__XXXXXX",
  "description": "一個uni-app應用",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {
    "usingComponents": true,
    "nvueStyleCompiler": "uni-app",
    "compilerVersion": 3,
    "splashscreen": {
      "alwaysShowBeforeRender": true,
      "waiting": true,
      "autoclose": true,
      "delay": 0
    }
  },
  "h5": {
    "publicPath": "/",
    "title": "我的uni-app",
    "template": "template.h5.html"
  },
  "mp-weixin": {
    "appid": "wx1234567890abcdef",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  }
}

平台特定配置 ​

  • app-plus：App平台配置
  • h5：H5平台配置
  • mp-weixin：微信小程式配置
  • mp-alipay：支付寶小程式配置

3. App.vue - 應用配置檔案 ​

App.vue 是應用程式的根元件，用於配置應用級別的生命週期和全域樣式。

vue
<script>
export default {
  onLaunch: function() {
    console.log('App Launch')
  },
  onShow: function() {
    console.log('App Show')
  },
  onHide: function() {
    console.log('App Hide')
  }
}
</script>

<style>
/* 每個頁面都會載入的公共樣式 */
page {
  background-color: #F4F5F6;
}

/* 全域字型設定 */
* {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}
</style>

4. main.js - 應用入口檔案 ​

main.js 是應用的入口檔案，用於初始化 Vue 應用。

javascript
import { createApp } from 'vue'
import App from './App.vue'

// 建立應用例項
const app = createApp(App)

// 配置全域屬性
app.config.globalProperties.$globalData = {
  version: '1.0.0',
  apiBaseUrl: 'https://api.example.com'
}

// 掛載應用
app.mount('#app')

目錄結構詳解 ​

pages/ - 頁面目錄 ​

pages 目錄存放所有的頁面檔案，每個頁面是一個獨立的目錄。

pages/
├── index/           # 首頁
│   ├── index.vue    # 頁面元件
│   └── index.json   # 頁面配置（可選）
├── user/
│   ├── user.vue     # 使用者頁面
│   └── user.json    # 頁面配置
└── detail/
    ├── detail.vue   # 詳情頁面
    └── detail.json  # 頁面配置

頁面檔案結構 ​

每個頁面目錄通常包含：

  • .vue 檔案：頁面元件
  • .json 檔案：頁面配置（可選）
  • .scss 檔案：頁面樣式（可選）

components/ - 元件目錄 ​

components 目錄存放可複用的 Vue 元件。

components/
├── common/           # 公共元件
│   ├── button.vue   # 按鈕元件
│   └── modal.vue    # 模態框元件
├── business/        # 業務元件
│   ├── user-card.vue # 使用者卡片
│   └── product-list.vue # 商品列表
└── layout/          # 佈局元件
    ├── header.vue   # 頭部元件
    └── footer.vue  # 底部元件

元件命名規範 ​

  • 使用帕斯卡命名法（PascalCase）
  • 檔案名與元件名保持一致
  • 避免使用保留字作為元件名

static/ - 靜態資源目錄 ​

static 目錄存放靜態資源檔案，如圖片、字型、JSON檔案等。

static/
├── images/          # 圖片資源
│   ├── logo.png     # 應用圖示
│   ├── banner.jpg   # 橫幅圖片
│   └── icons/       # 圖示檔案
│       ├── home.png
│       └── user.png
├── fonts/           # 字型檔案
│   ├── font.woff
│   └── font.woff2
└── data/            # 靜態資料
    └── cities.json   # 城市資料

靜態資源使用 ​

vue
<template>
  <view>
    <!-- 使用本地圖片 -->
    <image src="/static/images/logo.png"></image>
    
    <!-- 使用網路圖片 -->
    <image src="https://example.com/image.jpg"></image>
  </view>
</template>

utils/ - 工具函數目錄 ​

utils 目錄存放工具函數和輔助方法。

utils/
├── request.js       # 網路請求封裝
├── storage.js       # 本地儲存工具
├── validate.js      # 表單驗證工具
├── format.js        # 資料格式化工具
└── index.js         # 工具函數入口

工具函數示例 ​

javascript
// utils/request.js
export const request = (options) => {
  return new Promise((resolve, reject) => {
    uni.request({
      ...options,
      success: (res) => resolve(res),
      fail: (err) => reject(err)
    })
  })
}

// utils/storage.js
export const storage = {
  set: (key, value) => {
    uni.setStorageSync(key, value)
  },
  get: (key) => {
    return uni.getStorageSync(key)
  },
  remove: (key) => {
    uni.removeStorageSync(key)
  }
}

進階目錄結構 ​

uni_modules/ - 外掛目錄 ​

uni_modules 目錄存放透過 uni_modules 機制安裝的外掛。

uni_modules/
├── uni-ui/          # uni-ui元件庫
│   ├── components/
│   ├── static/
│   └── package.json
└── uni-request/     # 請求外掛
    ├── lib/
    └── package.json

store/ - 狀態管理目錄 ​

store 目錄存放 Vuex 狀態管理相關檔案。

store/
├── modules/         # 模組化狀態
│   ├── user.js      # 使用者狀態
│   ├── app.js       # 應用狀態
│   └── cart.js      # 購物車狀態
├── getters.js       # 計算屬性
├── mutations.js     # 同步操作
├── actions.js       # 非同步操作
└── index.js         # 入口檔案

api/ - API介面目錄 ​

api 目錄存放 API 介面相關檔案。

api/
├── user.js          # 使用者相關API
├── product.js       # 商品相關API
├── order.js         # 訂單相關API
└── index.js         # API入口

最佳實踐 ​

1. 目錄組織原則 ​

  • 功能導向：按功能模組組織目錄
  • 層次清晰：保持目錄層次簡單明瞭
  • 命名規範：使用有意義的目錄名
  • 避免過深：目錄層級不宜過深

2. 檔案命名規範 ​

  • 使用小寫字母和連字元
  • 避免使用特殊字元
  • 保持檔案名簡潔明瞭
  • 遵循 Vue 元件命名規範

3. 程式碼組織 ​

  • 單一職責原則：每個檔案只負責一個功能
  • 模組化設計：將相關功能組織在一起
  • 依賴管理：明確模組間的依賴關係
  • 註釋規範：為重要程式碼新增註釋

常見問題 ​

Q: 如何新增新的頁面？ ​

A: 在 pages 目錄下建立新的頁面目錄，然後在 pages.json 中配置頁面路徑。

Q: 如何建立可複用元件？ ​

A: 在 components 目錄下建立 Vue 元件，然後在需要使用的頁面中匯入和使用。

Q: 靜態資源應該放在哪裡？ ​

A: 靜態資源應該放在 static 目錄下，使用絕對路徑引用。

Q: 如何管理全域狀態？ ​

A: 可以使用 Vuex 進行狀態管理，相關檔案放在 store 目錄下。

理解專案結構是高效開發的基礎，希望本文對您有所幫助！

一次開發，多端部署 - 讓跨平台開發更簡單

Copyright © 2025 yanshengcha.com | Sitemap