第二章小程序目录结构与核心文件详解

📚 系列教程：微信小程序投票系统完整开发

🔗 上一章：第一章 - 微信小程序概述与开发准备

🔗 下一章：第三章 - WXML 所有表单组件与使用

2.1 完整目录结构

复制代码

wx/page/                          ← 小程序根目录
├── app.js                        ← 全局逻辑入口（必须）
├── app.json                      ← 全局配置（必须）
├── app.wxss                      ← 全局样式（可选）
├── project.config.json           ← 开发工具配置
├── project.private.config.json   ← 个人开发配置（不提交 git）
├── sitemap.json                  ← 搜索索引配置
└── pages/                        ← 页面目录
    ├── index/                    ← 首页
    │   ├── index.js              ← 页面逻辑
    │   ├── index.json            ← 页面配置（覆盖全局）
    │   ├── index.wxml            ← 页面结构
    │   └── index.wxss            ← 页面样式
    ├── create/                   ← 创建投票页
    │   ├── create.js
    │   ├── create.json
    │   ├── create.wxml
    │   └── create.wxss
    ├── vote/                     ← 投票页
    │   ├── vote.js
    │   ├── vote.json
    │   ├── vote.wxml
    │   └── vote.wxss
    └── result/                   ← 结果页
        ├── result.js
        ├── result.json
        ├── result.wxml
        └── result.wxss

📌 规律：每个页面由 4 个同名文件组成（js / json / wxml / wxss），其中 json 和 wxss 可以省略。

2.2 app.json --- 全局配置文件

app.json 是小程序的"大脑配置"，控制页面路由、窗口外观、底部导航栏等。

完整配置示例（投票系统）

json 复制代码

{{
  "pages": [
    "pages/index/index",
    "pages/create/create",
    "pages/vote/vote",
    "pages/result/result"
  ],
  "window": {
    "backgroundTextStyle": "light",
    "navigationBarBackgroundColor": "#6C63FF",
    "navigationBarTitleText": "统计小工具",
    "navigationBarTextStyle": "white",
    "backgroundColor": "#f5f5f5"
  },
  "style": "v2",
  "sitemapLocation": "sitemap.json"
}

pages 配置说明

json 复制代码

"pages": [
  "pages/index/index",    ← 第一个页面是默认首页（启动页）
  "pages/create/create",
  "pages/vote/vote",
  "pages/result/result"
]

💡 技巧：在 app.json 的 pages 数组中新增一行路径，保存后开发者工具会自动创建对应的页面文件夹和4个文件，非常方便。

window 配置说明

配置项	值	说明
`backgroundTextStyle`	`"light"`	下拉 loading 的样式，仅支持 `dark` / `light`
`navigationBarBackgroundColor`	`"#6C63FF"`	导航栏背景颜色（十六进制代码）
`navigationBarTitleText`	`"统计小工具"`	导航栏标题文字内容
`navigationBarTextStyle`	`"white"`	导航栏标题颜色，仅支持 `black` / `white`
`backgroundColor`	`"#f5f5f5"`	窗口的背景色（页面内容的背景色）

2.3 app.js --- 全局逻辑文件

app.js 是整个小程序的入口，负责全局状态管理和生命周期处理。

结构模板

javascript 复制代码

App({
  // 全局数据（类似 Vuex/Redux 的 state）
  globalData: {
    userInfo: null,
    openid: '',
    baseUrl: 'https://www.chinahanwucun.cn',
    // 内部状态（约定 _ 开头）
    _openidReady: false,
    _openidCallbacks: []
  },

  // ===== 生命周期 =====

  onLaunch(options) {
    // 冷启动时触发（小程序首次打开）
    // options.scene    场景值（1001=发现页，1005=顶部搜索等）
    // options.query    启动参数
    // options.path     启动页面路径
    console.log('小程序启动', options)
  },

  onShow(options) {
    // 每次切换到前台都触发
  },

  onHide() {
    // 切换到后台（按 Home 键或切换到其他 App）
  },

  onError(msg) {
    // 全局 JS 错误监听
    console.error('全局错误:', msg)
  },

  onPageNotFound(res) {
    // 页面不存在（比如分享链接对应的页面被删除了）
    wx.redirectTo({ url: '/pages/index/index' })
  },

  // ===== 自定义全局方法 =====

  getOpenid(callback) {
    if (this.globalData._openidReady) {
      callback(this.globalData.openid)
    } else {
      this.globalData._openidCallbacks.push(callback)
    }
  }
})

在页面中使用 app.js 的数据和方法

javascript 复制代码

// 页面 .js 文件头部
const app = getApp()

Page({
  onLoad() {
    // 访问全局数据
    console.log(app.globalData.baseUrl)

    // 调用全局方法
    app.getOpenid(openid => {
      console.log('openid:', openid)
    })
  }
})

2.4 app.wxss --- 全局样式

全局样式中定义的类名，所有页面都可以直接使用，无需 import。

css 复制代码

/* app.wxss */
page {
  background-color: #f5f6fa;
  font-family: -apple-system, 'PingFang SC', 'Helvetica Neue', sans-serif;
  font-size: 28rpx;
  color: #333;
}

/* 通用卡片 */
.card {
  background: #fff;
  border-radius: 20rpx;
  padding: 32rpx;
  margin: 24rpx 24rpx 0;
  box-shadow: 0 4rpx 20rpx rgba(0,0,0,0.06);
}

/* 通用按钮 */
.btn-primary {
  background: linear-gradient(135deg, #6C63FF, #9B8FFF);
  color: #fff;
  border-radius: 50rpx;
  font-size: 32rpx;
  font-weight: 600;
  border: none;
  padding: 0 60rpx;
  height: 88rpx;
  line-height: 88rpx;
  letter-spacing: 2rpx;
  box-shadow: 0 8rpx 24rpx rgba(108,99,255,0.35);
}

.btn-primary::after { border: none; }

.btn-outline {
  background: transparent;
  color: #6C63FF;
  border: 2rpx solid #6C63FF;
  border-radius: 50rpx;
  font-size: 28rpx;
  padding: 0 40rpx;
  height: 72rpx;
  line-height: 72rpx;
}
.btn-outline::after { border: none; }

2.5 页面 .json 配置文件

每个页面可以有自己的 .json 文件，覆盖 app.json 中 window 的配置。

json 复制代码

{
  "navigationBarTitleText": "发起投票",
  "navigationBarBackgroundColor": "#07C160",
  "navigationBarTextStyle": "white",
  "enablePullDownRefresh": true,
  "backgroundTextStyle": "light",
  "usingComponents": {}
}

📌 usingComponents 用于引入自定义组件，暂时留空即可。

2.6 sitemap.json --- 搜索配置

控制小程序页面是否允许被微信搜索索引（"微信搜索"功能）。

json 复制代码

{
  "desc": "关于本文件的更多信息，请参考文档 https://developers.weixin.qq.com/miniprogram/dev/framework/sitemap.html",
  "rules": [
    {
      "action": "allow",
      "page": "*"
    }
  ]
}

2.7 project.config.json --- 工具配置

json 复制代码

{
  "appid": "你的AppID",
  "projectname": "vote-miniprogram",
  "compileType": "miniprogram",
  "libVersion": "3.4.8",
  "setting": {
    "urlCheck": true,
    "es6": true,
    "enhance": true,
    "postcss": true,
    "preloadBackgroundData": false,
    "minified": true
  }
}

2.8 页面文件的编写顺序建议

开发一个新页面的推荐顺序：

复制代码

1. 在 app.json 的 pages 中添加路径 → 自动生成文件
2. 在 .json 中配置导航栏标题
3. 在 .js 的 data 中定义页面数据结构
4. 在 .wxml 中写页面骨架（先不加样式）
5. 在 .wxss 中完善样式
6. 回到 .js 中完善逻辑（onLoad、事件处理等）

本章小结

✅ 掌握了小程序完整的目录结构

✅ 理解了 app.json 中页面路由、窗口配置、tabBar 的写法

✅ 学会了 app.js 的全局生命周期和全局数据管理

✅ 掌握了 app.wxss 的全局样式定义方式

✅ 了解了各配置文件的作用和编写顺序

下一章：深入学习 WXML 的所有表单组件，这是构建投票界面的基础。

第二章 小程序目录结构与核心文件详解

第二章 小程序目录结构与核心文件详解

2.1 完整目录结构

2.2 app.json --- 全局配置文件

完整配置示例（投票系统）

pages 配置说明

window 配置说明

2.3 app.js --- 全局逻辑文件

结构模板

在页面中使用 app.js 的数据和方法

2.4 app.wxss --- 全局样式

2.5 页面 .json 配置文件

2.6 sitemap.json --- 搜索配置

2.7 project.config.json --- 工具配置

2.8 页面文件的编写顺序建议

本章小结

第二章小程序目录结构与核心文件详解

第二章小程序目录结构与核心文件详解