小程序开发入门：从零掌握基础代码结构

小程序作为一种“用完即走、无需安装”的轻应用，凭借微信、支付宝等超级App的流量生态，已成为前端开发者的必备技能。无论你打算开发一个电商工具、信息展示页，还是复杂的互动社区，理解其基础代码结构都是第一步。

本文以微信小程序为例，从项目文件结构、页面组成、数据绑定、事件响应到常见 API 调用，手把手带你写出一个可运行的小程序核心模块。

代码基于微信小程序基础库 3.x，兼容绝大多数真机与开发者工具。

一、小程序项目的最小构成

一个最简单的微信小程序至少包含以下文件：

text

复制

下载

my-app/ ├── app.js # 全局逻辑 ├── app.json # 全局配置（导航栏、窗口样式、页面路径等） ├── app.wxss # 全局样式（可选） └── pages/ └── index/ ├── index.js # 页面逻辑 ├── index.wxml # 页面结构（类似HTML） ├── index.wxss # 页面样式 └── index.json # 页面配置（可选）

1.1 全局配置app.json

所有小程序都必须包含app.json，它告诉微信小程序框架项目中有哪些页面、窗口外观如何：

json

复制

下载

{ "pages": [ "pages/index/index", "pages/logs/logs" ], "window": { "navigationBarBackgroundColor": "#1677ff", "navigationBarTitleText": "我的小程序", "navigationBarTextStyle": "white", "backgroundColor": "#f8f8f8" }, "tabBar": { "list": [ { "pagePath": "pages/index/index", "text": "首页", "iconPath": "images/home.png", "selectedIconPath": "images/home_active.png" }, { "pagePath": "pages/logs/logs", "text": "日志", "iconPath": "images/log.png", "selectedIconPath": "images/log_active.png" } ] }, "style": "v2", "sitemapLocation": "sitemap.json" }

• pages数组第一项为启动页面。

• window定义所有页面的默认导航栏、背景色等。

• tabBar用于底部导航栏（至少两项，最多五项）。

1.2 全局逻辑app.js

App()函数注册小程序实例，可定义全局数据与生命周期：

javascript

复制

下载

// app.js App({ onLaunch(options) { // 小程序启动时执行 console.log('App launched', options); }, globalData: { userInfo: null, apiBase: 'https://api.example.com' } });

其他页面可通过getApp()访问这些全局数据。

二、页面的四大组成文件

以首页pages/index/index为例，四个文件协同工作。

2.1 页面结构.wxml—— 相当于 HTML

WXML 提供了数据绑定、条件渲染、循环等能力：

xml

复制

下载

运行

<!--pages/index/index.wxml--> <view class="container"> <!-- 数据绑定：{{ }} --> <text class="title">{{title}}</text> <!-- 条件渲染 --> <view wx:if="{{showTip}}" class="tip">温馨提示：点击按钮获取数据</view> <!-- 列表渲染 --> <view wx:for="{{items}}" wx:key="index" class="item"> <text>{{index + 1}}. {{item.name}}</text> </view> <!-- 事件绑定：bindtap --> <button type="primary" bindtap="onFetchData">请求数据</button> <!-- 展示网络返回结果 --> <view wx:if="{{responseData}}" class="response"> <text>{{responseData}}</text> </view> </view>

常用组件：view（容器）、text（文本）、button、image、input、scroll-view等。

2.2 页面样式.wxss—— 扩展的 CSS

WXSS 基本支持 CSS 全部特性，并加入rpx（响应式像素）单位：

css

复制

下载

/* pages/index/index.wxss */ .container { padding: 40rpx; /* rpx 可根据屏幕宽度自适应，1rpx = 屏幕宽/750 */ background-color: #f5f5f5; min-height: 100vh; } .title { font-size: 36rpx; font-weight: bold; color: #1677ff; display: block; margin-bottom: 30rpx; } .item { background: white; padding: 20rpx; margin-bottom: 20rpx; border-radius: 16rpx; box-shadow: 0 2rpx 8rpx rgba(0,0,0,0.05); } .tip { color: #ff6600; font-size: 28rpx; margin: 20rpx 0; } .response { margin-top: 30rpx; background: #eef2ff; padding: 20rpx; border-radius: 12rpx; word-break: break-all; }

注意：小程序不支持通配符*选择器，且部分伪类（如:hover）只对特定组件生效。

2.3 页面逻辑.js—— Page 对象

Page()函数定义页面数据、生命周期、事件处理函数：

javascript

复制

下载

// pages/index/index.js Page({ data: { title: '小程序开发示例', showTip: true, items: [ { name: '苹果' }, { name: '香蕉' }, { name: '橙子' } ], responseData: '' }, onLoad(options) { // 页面加载时触发，options 为跳转参数 console.log('页面加载', options); // 可以在这里发起初始请求 this.loadInitialData(); }, onShow() { // 页面显示时触发（包括从后台切回） console.log('页面显示'); }, loadInitialData() { // 模拟本地数据展示 this.setData({ showTip: false }); }, // 事件处理：获取网络数据 onFetchData() { const that = this; wx.showLoading({ title: '加载中...' }); wx.request({ url: 'https://jsonplaceholder.typicode.com/posts/1', method: 'GET', success(res) { wx.hideLoading(); if (res.statusCode === 200) { that.setData({ responseData: JSON.stringify(res.data, null, 2) }); } else { wx.showToast({ title: '请求失败', icon: 'none' }); } }, fail(err) { wx.hideLoading(); wx.showToast({ title: '网络错误', icon: 'error' }); console.error(err); } }); } });

核心概念：

• this.setData()是更新界面和数据的唯一方法，直接修改this.data不会触发视图更新。

• 小程序不支持 Vue 中的双向绑定，需手动监听input事件并setData。

2.4 页面配置.json—— 覆盖全局设置

若某个页面需要独立配置导航栏或下拉刷新，可在同名的.json中声明：

json

复制

下载

{ "usingComponents": {}, "navigationBarTitleText": "首页 - 定制标题", "enablePullDownRefresh": true, "backgroundColor": "#eeeeee" }

三、数据绑定与事件响应的深入细节

3.1 数据绑定语法

WXML 中用双大括号{{ }}包裹变量，支持简单运算：

xml

复制

下载

运行

<view>计算：{{a + b}}</view> <view>三元：{{gender === 1 ? '男' : '女'}}</view> <view hidden="{{flag ? true : false}}">条件隐藏</view>

注意：不能在花括号内调用函数或定义复杂对象，应在Page.data中预先处理。

3.2 条件与循环

• wx:if/wx:elif/wx:else：惰性渲染，适合切换频率低的情况。

• hidden：组件始终渲染，仅控制显示隐藏，适合高频切换。

• wx:for：循环数组，必须指定wx:key以提升重渲染性能（可用*this或唯一字段）。

xml

复制

下载

运行

<view wx:for="{{users}}" wx:key="id"> 姓名：{{item.name}}，年龄：{{item.age}} </view>

3.3 事件绑定与传参

常用事件：bindtap（点击）、bindinput（输入）、bindconfirm（确认）。

传递自定义参数：使用data-*属性，然后在事件对象的currentTarget.dataset中获取。

xml

复制

下载

运行

<button bindtap="onDelete" data-id="{{item.id}}" data-name="{{item.name}}">删除</button>

javascript

复制

下载

onDelete(e) { const { id, name } = e.currentTarget.dataset; console.log(`删除 id=${id}, name=${name}`); // 执行删除逻辑 }

表单输入双向模拟：

xml

复制

下载

运行

<input placeholder="请输入用户名" bindinput="onInputUserName" value="{{userName}}"/>

javascript

复制

下载

data: { userName: '' }, onInputUserName(e) { this.setData({ userName: e.detail.value }); }

四、常用 API 速览（基础代码必备）

4.1 网络请求wx.request

类似浏览器fetch，但需配置合法域名（在微信公众平台后台设置 request 域名）。

javascript

复制

下载

wx.request({ url: 'https://api.com/data', method: 'POST', data: { key: 'value' }, header: { 'content-type': 'application/json' }, success(res) { /* 处理成功 */ }, fail(err) { /* 处理失败 */ } });

4.2 本地存储wx.setStorageSync/wx.getStorageSync

同步 API 更适合简单场景：

javascript

复制

下载

// 存储 wx.setStorageSync('token', 'abc123'); // 读取 const token = wx.getStorageSync('token'); // 删除 wx.removeStorageSync('token');

异步版本（wx.setStorage）不会阻塞 UI，适合大数据。

4.3 界面交互

• wx.showToast：轻提示

• wx.showModal：确认对话框

• wx.showLoading/wx.hideLoading

• wx.showActionSheet：底部操作菜单

javascript

复制

下载

wx.showModal({ title: '提示', content: '确定要删除吗？', success(res) { if (res.confirm) { // 确认操作 } } });

4.4 页面跳转

javascript

复制

下载

// 保留当前页面，跳转到新页面（可返回） wx.navigateTo({ url: '/pages/detail/detail?id=123' }); // 关闭当前页面，跳转到新页面 wx.redirectTo({ url: '/pages/login/login' }); // 切换到 tabBar 页面 wx.switchTab({ url: '/pages/index/index' }); // 返回上一页 wx.navigateBack({ delta: 1 });

页面间传参通过 URL query 字符串，在目标页面的onLoad(options)中获取。

五、一个完整的交互示例：待办清单（Todo）核心代码

为了巩固上述知识点，下面实现一个简单的待办清单页面。

index.wxml

xml

复制

下载

运行

<view class="todo-container"> <view class="input-row"> <input placeholder="输入新任务" bindinput="onInput" value="{{newTodo}}" /> <button type="primary" size="mini" bindtap="addTodo">添加</button> </view> <view wx:for="{{todos}}" wx:key="id" class="todo-item"> <checkbox value="{{item.id}}" checked="{{item.completed}}" bindtap="toggleTodo" data-id="{{item.id}}"/> <text class="{{item.completed ? 'completed' : ''}}">{{item.text}}</text> <button size="mini" type="warn" bindtap="deleteTodo" data-id="{{item.id}}">删除</button> </view> <view class="stats">共 {{todos.length}} 项，已完成 {{completedCount}} 项</view> </view>

index.js

javascript

复制

下载

Page({ data: { newTodo: '', todos: [], completedCount: 0 }, onLoad() { // 从本地存储加载数据 const stored = wx.getStorageSync('todos'); if (stored) { this.setData({ todos: stored }); this.updateCompletedCount(); } }, onInput(e) { this.setData({ newTodo: e.detail.value }); }, addTodo() { if (!this.data.newTodo.trim()) return; const newItem = { id: Date.now(), text: this.data.newTodo, completed: false }; const newTodos = [...this.data.todos, newItem]; this.setData({ todos: newTodos, newTodo: '' }); this.updateCompletedCount(); wx.setStorageSync('todos', newTodos); }, toggleTodo(e) { const id = e.currentTarget.dataset.id; const todos = this.data.todos.map(item => { if (item.id === id) item.completed = !item.completed; return item; }); this.setData({ todos }); this.updateCompletedCount(); wx.setStorageSync('todos', todos); }, deleteTodo(e) { const id = e.currentTarget.dataset.id; const todos = this.data.todos.filter(item => item.id !== id); this.setData({ todos }); this.updateCompletedCount(); wx.setStorageSync('todos', todos); }, updateCompletedCount() { const count = this.data.todos.filter(item => item.completed).length; this.setData({ completedCount: count }); } });

index.wxss略，但你已经掌握了基础样式写法。

六、常见错误与排坑指南

1. setData 的数据量过大
   避免一次性传递大量数据（例如超长数组），可考虑分页加载。单次setData的数据大小建议不超过 1MB。

2. this 指向丢失
   在异步回调或嵌套函数中，提前用const that = this保存，或使用箭头函数。

3. 页面路径大小写敏感
   app.json中的路径必须与实际文件路径完全一致（包括大小写），否则开发者工具不会报错但真机无法加载。

4. 请求域名未配置
   开发阶段可在开发者工具中勾选“不校验合法域名”，但正式上线前务必在后台配置。

5. 不支持 DOM 操作
   小程序无法通过document或window访问节点。若需获取元素宽高，使用wx.createSelectorQuery()。

结语

小程序的“基础代码”并不复杂——它本质上是经过封装的MVVM 框架，WXML 提供视图模板，JS 管理数据与逻辑，WXSS 负责样式。掌握上述.wxml、.js、.wxss、.json四件套，理解setData和生命周期，便已经跨过了最核心的门槛。

建议你立即打开微信开发者工具，创建一个空白项目，亲手把待办清单的例子敲一遍，并尝试增加“编辑任务”或“清空已完成”等功能。不断迭代这些小模块，小程序开发能力就会快速成长。