微信小程序（TypeScript）开发指南

一、前置准备：环境搭建+项目创建
- [1.1 环境搭建（必备工具）](#1.1 环境搭建（必备工具）)
- [1.2 新建项目（模板选择+目录生成）](#1.2 新建项目（模板选择+目录生成）)
- [1.3 新增页面的两种方式（后续扩展用）](#1.3 新增页面的两种方式（后续扩展用）)
- - 方式1：工具创建（推荐，新手首选）
  - 方式2：手动创建（熟悉目录结构用）
二、项目启动与调试（怎么运行小程序）
- [2.1 启动项目（核心步骤）](#2.1 启动项目（核心步骤）)
- [2.2 预览与调试（新手必备技能）](#2.2 预览与调试（新手必备技能）)
- [2.3 重启与停止](#2.3 重启与停止)
三、工程目录树形图
四、目录解读
- [1. 根目录（WX-FRONT/）：工程配置层](#1. 根目录（WX-FRONT/）：工程配置层)
- [2. miniprogram/：源码核心层（开发主战场）](#2. miniprogram/：源码核心层（开发主战场）)
五、新手实操：基于你的目录新增"商品列表页"
六、关键知识点（新手必记）

一、前置准备：环境搭建+项目创建

1.1 环境搭建（必备工具）

下载微信开发者工具：官网地址 https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html，选择对应系统（Windows/Mac）安装
获取小程序AppID （关键步骤）：
1. 访问微信公众平台 https://mp.weixin.qq.com/，用个人微信注册账号（免费）
2. 登录后进入「开发 → 开发设置」，复制你的「AppID」（格式类似 wx1234567890abcdef，勿用测试号）

1.2 新建项目（模板选择+目录生成）

打开微信开发者工具，点击左侧「+」号 → 选择「新小程序项目」
填写项目信息（生成你当前的 WX-FRONT/ 目录）：
- 项目名称：自定义（如「小超市小程序」）
- 目录：选择本地空文件夹（后续项目文件会全部放在这里）
- AppID：粘贴刚复制的个人AppID（必须填写，否则无法正常启动）
- 模板选择：点击「模板」下拉框 → 选择「TypeScript基础模板」（当前目录的来源）
- 勾选：「不使用云服务」（纯前端开发，后续可对接Java后端）
点击「创建」→ 工具自动生成完整目录结构（即下文的「工程目录树形图」）

1.3 新增页面的两种方式（后续扩展用）

后续需要添加页面（如商品列表、购物车）时，推荐用工具创建（自动注册路由），两种方式如下：

方式1：工具创建（推荐，新手首选）

右键点击 miniprogram/pages/ 目录 → 选择「新建页面」
输入页面名称（如 goodsList）→ 默认勾选「TypeScript」（与项目模板一致）
点击「创建」→ 自动生成「页面4件套」（.json/.ts/.wxml/.wxss），并自动在 app.json 中注册路由（无需手动操作）

方式2：手动创建（熟悉目录结构用）

打开 miniprogram/pages/ → 新建文件夹（如 goodsList，目录名=页面名）
在文件夹内手动创建4个文件，文件名必须与目录名一致：
- goodsList.json（页面配置）、goodsList.ts（逻辑）、goodsList.wxml（结构）、goodsList.wxss（样式）
手动在 app.json 的 pages 数组中添加页面路径（如 "pages/goodsList/goodsList"）

二、项目启动与调试（怎么运行小程序）

2.1 启动项目（核心步骤）

打开微信开发者工具，左侧选择你的 WX-FRONT/ 项目
确认 project.config.json 中的 appid 已填写正确（否则启动失败）
点击工具顶部「编译」按钮（绿色三角图标）→ 等待1-2秒
右侧「模拟器」自动渲染小程序首页（默认显示 pages/index/index）→ 启动成功

2.2 预览与调试（新手必备技能）

模拟器预览：右侧可选择手机型号（如iPhone 14、华为Mate 40），查看不同设备的适配效果
真机预览：点击顶部「预览」按钮 → 生成二维码 → 手机微信扫描 → 查看真实运行效果（需手机和电脑连同一网络）
调试工具使用 （底部菜单栏）：
- 「Console」：查看代码报错、打印 console.log 日志
- 「Elements」：实时修改 wxml 结构和 wxss 样式，预览效果
- 「Sources」：查看项目源码，打断点调试 ts 逻辑
- 「Storage」：查看/删除本地缓存数据（如 wx.setStorageSync 存储的数据）

2.3 重启与停止

重启项目：修改代码后，点击「重新编译」按钮（编译按钮右侧）→ 模拟器刷新最新代码
停止项目：无需手动停止，关闭模拟器或切换其他项目即可

三、工程目录树形图

复制代码

WX-FRONT/
├─ miniprogram/               # 小程序源码核心目录（运行时实际加载）
│  ├─ pages/                  # 页面目录（当前包含2个示例页面）
│  │  ├─ index/               # 首页（默认示例页）
│  │  │  ├─ index.json        # 首页配置文件
│  │  │  ├─ index.ts          # 首页逻辑文件
│  │  │  ├─ index.wxml        # 首页结构文件
│  │  │  └─ index.wxss        # 首页样式文件
│  │  └─ logs/                # 日志页（默认示例页）
│  │     ├─ logs.json         # 日志页配置文件
│  │     ├─ logs.ts           # 日志页逻辑文件
│  │     ├─ logs.wxml         # 日志页结构文件
│  │     └─ logs.wxss         # 日志页样式文件
│  ├─ utils/                  # 通用工具目录
│  │  └─ util.ts              # 基础工具函数（如日期格式化）
│  ├─ app.json                # 全局配置（路由、窗口样式）
│  ├─ app.ts                  # 全局逻辑入口（启动初始化）
│  └─ app.wxss                # 全局样式（所有页面共享）
├─ typings/                   # TS类型声明目录（提供API智能提示）
│  ├─ types/                  # 自定义类型目录（当前为空，可自行添加）
│  └─ wx/                     # 微信API类型声明（工具自动生成）
│     ├─ index.d.ts           # 微信全局类型声明
│     ├─ lib.wx.api.d.ts      # 微信API类型声明
│     ├─ lib.wx.app.d.ts      # 小程序App类型声明
│     └─ ...（其他微信框架类型文件）
├─ package.json               # npm依赖配置（仅声明TS类型包）
├─ project.config.json        # 工程公共配置（关联AppID、指定源码目录）
├─ project.private.config.json # 本机私有配置（调试开关等）
├─ README.md                  # 项目说明文档（可自行编辑）
└─ tsconfig.json              # TS编译配置（类型检查规则）

四、目录解读

1. 根目录（WX-FRONT/）：工程配置层

project.config.json：微信开发者工具的核心配置
- 作用：关联你的小程序AppID、指定源码目录为 miniprogram/
- 新手操作：找到 appid 字段，粘贴你的小程序AppID（从微信公众平台获取）
tsconfig.json：TS编译规则配置
- 作用：开启严格类型检查（避免低级错误），控制TS转JS的规则
- 新手操作：无需修改，默认配置满足需求
typings/：TS类型声明目录
- 作用：存放 .d.ts 文件，让编辑器识别 wx 对象、小程序API的类型（写代码时有智能提示）
- 新手操作：不用手动修改，工具自动维护

2. miniprogram/：源码核心层（开发主战场）

（1）3个全局文件（小程序入口）

app.json：全局配置文件
- 核心作用：管理页面路由（pages 数组）、设置窗口样式（导航栏标题/颜色）
- 新手操作：新增页面后，把页面路径添加到 pages 数组里，小程序才能识别这个页面
app.ts：全局逻辑文件
- 核心作用：注册小程序实例，处理启动时的初始化（如 onLaunch 生命周期）
- 新手操作：在 onLaunch 里写小程序启动时要做的事（比如读取本地缓存、初始化全局数据）
app.wxss：全局样式文件
- 核心作用：定义所有页面共享的基础样式（比如主题色、通用字体）
- 新手操作：在这里写的样式，所有页面都会生效（比如设置 page { background-color: #f5f5f5; } 让所有页面背景统一）

（2）pages/：页面目录（当前有2个示例页）

每个页面都是「1个目录+4个文件」（简称"页面4件套"），这是小程序的固定规则：

index/（首页）：默认示例页，展示"获取头像昵称"功能
- index.wxml：页面结构（类似HTML，写按钮、文字的位置）
- index.wxss：页面专属样式（只对首页生效，比如调整按钮大小）
- index.ts：页面逻辑（处理点击事件、存页面数据）
- index.json：页面配置（比如改首页的导航栏标题）
logs/（日志页）：默认示例页，展示本地缓存的日志
- 作用：演示页面跳转、本地缓存读取的功能
- 新手参考：可以看 logs.ts 里的 wx.getStorageSync 怎么读缓存，wx.navigateTo 怎么跳页面

（3）utils/：通用工具目录

util.ts ：基础工具函数
- 当前示例：有 formatTime 函数，用来把时间戳转成可读的日期格式
- 新手操作：可以在这里加自己的工具函数（比如价格格式化、字符串处理），所有页面都能调用

五、新手实操：基于你的目录新增"商品列表页"

现在教你在当前目录基础上，新增一个"商品列表页"，学会这个就能扩展任意页面：

步骤1：在pages/下新建页面目录

打开 miniprogram/pages/，新建 goodsList 目录
在 goodsList 里新建4个文件：goodsList.json、goodsList.ts、goodsList.wxml、goodsList.wxss

步骤2：在app.json里注册页面路由

打开 miniprogram/app.json，把 "pages/goodsList/goodsList" 加到 pages 数组里（加在最前面会默认打开这个页）：

json 复制代码

{
  "pages": [
    "pages/goodsList/goodsList",  // 新增的商品列表页
    "pages/index/index",
    "pages/logs/logs"
  ],
  "window": {
    "backgroundTextStyle": "light",
    "navigationBarBackgroundColor": "#fff",
    "navigationBarTitleText": "小超市",  // 把标题改成"小超市"
    "navigationBarTextStyle": "black"
  }
}

步骤3：写商品列表页的代码

（1）goodsList.wxml（页面结构）

xml 复制代码

<view class="goods-container">
  <!-- 循环展示商品 -->
  <view class="goods-item" wx:for="{{ goodsList }}" wx:key="id">
    <image class="goods-img" src="/images/goods/{{ item.id }}.png"></image>
    <view class="goods-name">{{ item.name }}</view>
    <view class="goods-price">¥{{ item.price }}</view>
  </view>
</view>

（2）goodsList.ts（页面逻辑）

typescript 复制代码

// 定义商品类型（TS类型约束，避免写错数据）
interface Goods {
  id: number;
  name: string;
  price: number;
}

Component({
  // 页面数据
  data: {
    goodsList: [
      { id: 1, name: "红富士苹果", price: 19.9 },
      { id: 2, name: "原味牛奶", price: 59.9 },
      { id: 3, name: "全麦面包", price: 12.9 }
    ] as Goods[]
  }
});

（3）goodsList.wxss（页面样式）

css 复制代码

.goods-container {
  padding: 10rpx;
}
.goods-item {
  display: flex;
  margin-bottom: 15rpx;
  padding: 10rpx;
  border: 1rpx solid #eee;
  border-radius: 8rpx;
}
.goods-img {
  width: 120rpx;
  height: 120rpx;
  margin-right: 15rpx;
}
.goods-name {
  font-size: 28rpx;
  margin-bottom: 5rpx;
}
.goods-price {
  font-size: 30rpx;
  color: #f40;
}

步骤4：编译查看效果

点击微信开发者工具的「编译」按钮，模拟器会自动跳转到商品列表页（因 goodsList 在 pages 数组最前面），即可看到商品列表渲染效果！

六、关键知识点（新手必记）

页面必须注册 ：新增页面后，一定要在 app.json 的 pages 数组里加路径，否则小程序找不到这个页
4件套缺一不可：每个页面的4个文件（.json/.ts/.wxml/.wxss）必须齐全，文件名要和目录名一致
数据驱动视图 ：页面数据存在 data 里，用 {``{ 数据名 }} 显示在wxml里，改数据要写 this.setData({ 数据名: 新值 })
本地缓存 ：用 wx.setStorageSync 存数据、wx.getStorageSync 读数据（参考logs页的代码）
TS类型约束 ：定义接口（如 interface Goods）约束数据结构，避免类型错误（类似Java的实体类）