微信小程序(一)：前期准备和项目目录认识

前言

该文章记录一些工作中遇到的常见问题，以及一些解决办法，慢慢将会添加更多的问题记录，所有内容均从网上整理而来，加上自己的理解做一个整合，方便工作中使用。

前期准备

1. 申请小程序账号

小程序开发 与 网页开发不一样，在开始微信小程序开发之前，需要访问 微信公众平台，注册一个微信小程序账号。获取小程序 ID（AppID） 和一个 小程序密钥（AppSecret）

2. 下载微信开发者工具

微信官方提供了 微信开发者工具，利用开发者工具可以很方便地进行小程序开发、代码查看以及编辑、预览和发布等功能

一、基础知识

1.【创建项目】

1. 打开微信开发者工具，左侧选择小程序，点击 + 号即可新建项目

2. 填写项目信息，AppID：填写自己申请的小程序 AppID，选择不使用云服务，选择不使用模板

   

2.【小程序目录结构和文件介绍】

• 基本结构

  

3.【自定义构建 npm + 集成Sass】

1. 项目根目录下，创建miniprogram文件夹， 将以下文件放入其中

   • app.js/ app.json /app.wxss
   • sitemap.json
   • pages文件夹
   • utils文件夹
   • components文件夹

2. 项目根目录下，创建package.json文件

   使用 npm init -y 生成package.json

3. 在project.config.json设置配置项

   "miniprogramRoot": "miniprogram/", //指定小程序源码的目录
   "setting": {
       "packNpmManually": true, //开启自定义 node_modules 和 miniprogram_npm 位置的构建 npm 方式
       "packNpmRelationList": [
         {
           "packageJsonPath": "/package.json", //表示 node_modules 源对应的 package.json
           "miniprogramNpmDistDir": "/miniprogram" //表示 node_modules 的构建结果目标位置
         }
       ],
       "useCompilerPlugings": ["scss"], //使用scss，所有wxss文件可以改为scss文件
       ···
   },

4. 在微信开发者工具中，点击工具,点击构建npm,生成miniprogram_npm文件夹，将其放入miniprogram文件夹下

   

5. 如果需要将项目上传git，需要创建.gitignore文件

       dist/
       deploy_versions/
       .temp/
       .rn_temp/
       node_modules/
       .DS_Store

• 一个完整的小程序项目分为两个部分：主体文件 、页面文件

  1）主体文件 又称小程序全局文件，顾名思义，全局文件能够作用于整个小程序，影响到小程序的每个页面，且主体文件必须放到项目的根目录下，主要由三部分组成：

  文件名	作用	是否必须
  app.js	小程序入口文件	必须
  app.json	小程序的全局配置	必须
  app.wxss	小程序的全局样式	非必须

  2）页面文件 是每个页面所需的文件，小程序页面文件都存放在 pages 目录下，一个页面一个文件夹，每个页面通常由四个文件组成，每个文件只对当前页面有效：

  文件名	作用	是否必须
  .js	页面逻辑	必须
  .wxml	页面结构	必须
  .wxss	页面样式	非必须
  .json	页面配置	非必须

  📌 注意事项：页面文件的wxss、json 文件能够覆盖主体文件中的样式和配置

4.【创建新页面】

• 第一种方式：

  1. 在 pages 目录上 点击右键 新建文件夹，输入页面目录的名称，例如：list

  2. 在 list 目录上 点击右键 点击 page，输入页面文件的名称，例如：list

  📌 注意事项：

  • 一个页面一个文件夹
  • 在输入页面文件名称的时候，不要输入后缀名 ❗
  • 新建页面成功以后，会在 app.json 的 pages 选项中新增页面路径

• 第二种方式：

  在 app.json 的 pages 选项中，新增页面路径即可。在新增页面目录以后，会自动在 pages 目录下生成页面文件

5.【创建自定义组件】

• 组件类型

  1. 公共组件：将页面内的功能模块抽象成自定义组件，以便在不同的页面中重复使用；将其放在小程序的目录下的 components 文件夹中
  2. 页面组件：将复杂的页面拆分成多个低耦合的模块，有助于代码维护；将其放在小程序对应页面目录下

• 创建方法

  • 以公共组件为例，在小程序的目录下 components 文件夹里新建文件夹，文件夹命名组件的名称，在新建的组件文件夹上，点击右键，选择新建 Component，然后输入组件的名称（组件的名称建议和文件夹保持一致）

• 使用方法

  • 全局自定义组件-全局注册：在 app.json 文件中配置 usingComponents 节点进行引用声明，注册后可在任意组件使用

  • 页面自定义组件-局部注册：在页面的 json 文件中配置 usingComponents 节点进行引用声明，只可在当前页面使用

  //在要使用的地方---注册/引入
  {
    "usingComponents": {
      "custom-checkbox": "/components/custom-checkbox/custom-checkbox"
    }
  }

  <!-- 在要使用的地方---直接使用 -->
  <view>
    <!-- 将导入的自定义组件当成标签使用 -->
    <custom-checkbox/>
  </view>

6.【分包的创建和使用】

• 分包加载

  什么是分包加载 ❓

  小程序的代码通常是由许多页面、组件以及资源等组成，随着小程序功能的增加，代码量也会逐渐增加，体积过大就会导致用户打开速度变慢，影响用户的使用体验。

  分包加载是一种小程序优化技术。将小程序不同功能的代码，分别打包成不同的子包，在构建时打包成不同的分包，用户在使用时按需进行加载，在构建小程序分包项目时，构建会输出一个或多个分包。每个使用分包小程序必定含有一个主包。每个分包可以包含多个页面、组件、样式和逻辑等。当小程序需要使用某个分包时，才会加载该分包中的代码。

  主包： 包含默认启动页面 / TabBar 页面 以及 所有分包都需用到公共资源的包

  分包： 根据开发者的配置进行划分出来的子包

  

  目前小程序分包大小有以下限制：

  1. 整个小程序所有分包大小不超过 20MB

  2. 单个分包/主包大小不能超过 2MB

  📌 注意事项：

  ​ 整个小程序所有分包大小可能会随时调整，截止到目前整个小程序所有分包大小不超过 20M

• 分包的基本使用

  开发者在小程序的配置文件 app.json 中，通过 subPackages 或者 subpackages字段声明项目分包结构。

  每个分包需要指定 root 字段、name 字段和 pages 字段

  1. root 字段指定了分包的根目录，该目录下的所有文件都会被打包成一个独立的包
  2. name 字段为分包的名称，用于在代码中引用该分包
  3. pages 字段指定了该分包中包含的页面，可以使用通配符 * 匹配多个页面

  {
  
    "subPackages": [
      {
        "root": "modules/goodModule",
        "name": "goodModule",
        "pages": [
          "pages/list/list",
          "pages/detail/detail"
        ]
      },
      {
        "root": "modules/marketModule",
        "name": "marketModule",
        "pages": [
          "pages/market/market"
        ]
      }
    ]
  
  }

• 打包和引用原则(注意事项)

  打包原则：

  1. tabBar 页面必须在主包内

  2. 最外层的 pages 字段，属于主包的包含的页面

  3. 按 subpackages 配置路径进行打包，配置路径外的目录将被打包到主包中

  4. 分包之间不能相互嵌套，subpackage 的根目录不能是另外一个 subpackage 内的子目录

  引用原则：

  1. 主包不可以引用分包的资源，但分包可以使用主包的公共资源

  2. 分包与分包之间资源无法相互引用， 分包异步化时不受此条限制

• 独立分包的配置

  什么是独立分包：

  独立分包：独立分包是小程序中一种特殊类型的分包，可以独立于主包和其他分包运行。

  从独立分包中页面进入小程序时，不需要下载主包，但是当用户进入普通分包或主包内页面时，主包才会被下载 ！

  开发者可以将功能相对独立的页面配置到独立分包中，因为独立分包不依赖主包即可运行，可以很大程度上提升分包页面的启动速度

  如果是独立分包，不需要下载主包，直接就能够访问，独立分包是自己独立运行的

  而如果是其他分包，需要先下载主包，通过路径访问，才能加载对应路径的分包
  📌 注意事项：

  1. 独立分包中不能依赖主包和其他分包中的资源

  2. 主包中的 app.wxss 对独立分包无效

  3. App 只能在主包内定义，独立分包中不能定义 App，会造成无法预期的行为

  如何配置独立分包：

  开发者在app.json中找到需要配置为独立分包的subpackages字段

  在该字段配置项中定义independent字段声明对应分包为独立分包。

  落地代码：

  {
  
    "subPackages": [
      {
        "root": "modules/goodModule",
        "name": "goodModule",
        "pages": [
          "pages/list/list",
          "pages/detail/detail"
        ]
      },
      {
        "root": "modules/marketModule",
        "name": "marketModule",
        "pages": [
          "pages/market/market"
        ],
       "independent": true
      }
    ]
  }

• 分包预下载

  知识点：

  分包预下载是指访问小程序某个页面时，预先下载分包中的代码和资源，以提高用户的使用体验。当用户需要访问分包中的页面时，已经预先下载的代码和资源可以直接使用，通过分包预下载加快了页面的加载速度和显示速度。

  小程序的分包预下载需要在 app.json 中通过 preloadRule 字段设置预下载规则。preloadRule 是一个对象，对象的 key 表示访问哪个路径时进行预加载，value 是进入此页面的预下载配置，具有两个配置项：

  字段	类型	必填	默认值	说明
  packages	StringArray	是	无	预下载的分包名称，进入页面后预下载分包的 root 或 name __APP__ 表示主包。
  network	String	否	wifi	在指定网络下预下载， 可选值为： all: 不限网络 wifi: 仅wifi下预下载

  {
    "subPackages": [
      {
        "root": "modules/goodModule",
        "name": "goodModule",
        "pages": [
          "pages/list/list",
          "pages/detail/detail"
        ]
      },
      {
        "root": "modules/marketModule",
        "name": "marketModule",
        "pages": [
          "pages/market/market"
        ],
        "independent": true
      }
    ],
    "preloadRule": {
      "pages/index/index": {
        "network": "all",
        "packages": ["modules/goodModule"]
      },
      "modules/marketModule/pages/market/market": {
        "network": "all",
        "packages": ["__APP__"]
      }
    }
  }

  落地代码：

  {
    "pages": [
      "pages/index/index",
      "pages/user/user"
    ],
    "subPackages": [
      {
        "root": "pages/music",
        "name": "music",
        "pages": [
          "player/player",
          "lyric/lyric"
        ]
      },
      {
        "root": "pages/settings",
        "name": "settings",
        "pages": [
          "theme/theme",
          "language/language"
        ]
      }
    ],
    "preloadRule": {
      "pages/music/player/player": {
        "packages": ["settings"],
        "network": "wifi"
      }
    }
  }

二、VsCode 开发小程序项目（个人喜欢用vscode）

VsCode 对小程序开发支持的不是非常友好，如果想通过 VSCode 开发小程序项目，需要安装以下插件：

1. WXML - Language Service

   

2. prettier

   

3. 微信小程序开发工具

   

4. 微信小程序助手-Y

   

5. 小程序开发助手(可选)

   

配置详细插件：

1. 在【项目的根目录】下创建 .vscode 文件夹，注意：文件夹名字前面带 . 点❗

2. 在 .vscode 文件夹下，创建 settings.json，用来对安装的插件属性进行设置，具体属性设置从下面复制即可

   • 注意：.vscode 文件夹下的 settings.json 文件只对当前一个项目生效

3. 在【项目的根目录】下创建 .prettierrc 文件，进行 Prettier 代码规则的配置，规则从下面复制即可

4. 为了让 Prettier 配置项在微信开发者工具生效，需要在微信开发者工具中也安装 Prettier 扩展插件。

➡️ .vscode/settings.json

{
  // 保存文件时是否自动格式化
  "editor.formatOnSave": true,

  // ---------------- 以下是 [ prettier ] 插件配置 ----------------

  // 指定 javascript、wxss、scss、less、json、jsonc 等类型文件使用 prettier 进行格式化
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  "[wxss]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  "[scss]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  "[less]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // Prettier 的一个配置项，用于指定哪些文件类型需要使用 Prettier 进行格式化
  "prettier.documentSelectors": ["**/*.wxml", "**/*.wxss", "**/*.wxs"],

  // ---------------- 以下是 [ WXML - Language Service ] 插件配置 ----------------

  // wxml 文件使用 prettier 进行格式化
  "[wxml]": {
    // "qiu8310.minapp-vscode" 是 WXML - Language Service 插件提供的配置项
    // 此插件主要是针对小程序的 wxml 模板语言，可以自动补全所有的组件、组件属性、组件属性值等等

    // 如果是 VsCode 需要开启这个配置
    "editor.defaultFormatter": "qiu8310.minapp-vscode"

    // 如果是微信小程序，需要开启这个配置，通过 esbenp.prettier-vscode 对代码进行格式化
    // "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // 创建组件时使用的 css 后缀
  "minapp-vscode.cssExtname": "scss", // 默认 wxss，支持 styl sass scss less css

  // 指定 WXML 格式化工具
  "minapp-vscode.wxmlFormatter": "prettier",
  // 配置 prettier 代码规范
  "minapp-vscode.prettier": {
    "useTabs": false,
    "tabWidth": 2,
    "printWidth": 80
  },

  // ---------------- 以下是 [ 微信小程序助手-Y ] 插件配置 ----------------

  // 新增、删除小程序页面时，是否自动同步 app.json pages 路径配置，默认为 false
  "wechat-miniapp.sync.delete": true,
  // 设置小程序页面 wxss 样式文件的扩展名
  "wechat-miniapp.ext.style": "scss",

  // ---------------- 其他配置项 ----------------

  // 配置语言的文件关联，运行 .json 文件时写注释
  // 但在 app.json 和 page.json 中无法使用
  "files.associations": {
    "*.json": "jsonc"
  }
}

➡️ .prettierrc

{
  "semi": false,
  "singleQuote": true,
  "useTabs": false,
  "tabWidth": 2,
  "printWidth": 180,
  "trailingComma": "none",
  "overrides": [
    {
      "files": "*.wxml",
      "options": { "parser": "html" }
    },
    {
      "files": "*.wxss",
      "options": { "parser": "css" }
    },
    {
      "files": "*.wxs",
      "options": { "parser": "babel" }
    }
  ]
}

配置项	配置项含义
"semi": false	不要有分号
"singleQuote": true	使用单引号
"useTabs": false	缩进不使用 tab,使用空格
"tabWidth": 2	tab缩进为4个空格字符
"printWidth": 80	一行的字符数，如果超过会进行换行，默认为80
"trailingComma": "none"	尾随逗号问题，设置为none 不显示 逗号
"overrides": []	overrides 解析器：默认情况下，Prettier 会根据文件文件拓展名推断要使用的解析器

📌：注意事项：

项目根目录 .vscode 文件夹中 settings.json 文件只对当前项目生效❗

如果想配置项生效，还需要注意：

在 VsCode 中只能打开当前一个小程序项目，不能同时打开多个小程序项目❗ 且项目目录请勿嵌套打开 ❗

三、引入外部插件

1. 引入字体图标

• 第一步：项目设置：字体格式必须要勾选base64

  

  注意：字体格式必须要勾选base64

  

• 第二步：选择Font class ，然后下载至本地,得到 iconfont.css

  

• 第三步：在微信小程序项目中，创建iconfont/iconfont.wxss,在将iconfont.css所有内容复制进去，并将.font_family修改为.iconfont

  

  

• 第四步：在app.wxss中全局引入iconfont/iconfont.wxss

  @import './static/iconfont/iconfont.wxss';

• 第五步：使用方法：class="iconfont icon-名字"

  <text class="iconfont icon-xytk1"> </text>
  <text class="iconfont icon-jjdz"> </text>
  <text class="iconfont icon-bzgg" style="color:red"> </text>

• 【注意：自定义组件引用字体图标】

  //需要在其自定义组件的scss文件中，再次引入字体图标
  @import 'xxxx/iconfont/iconfont.wxss';

  ---

2. 引入vant/weapp

1. 下载npm i @vant/weapp

2. 在app.json（全局）或index.json（对应的页面）中引入组件

"usingComponents": { 
    "van-button": "@vant/weapp/button/index"
}

3. 在对应index.wxml使用

<van-button type="danger">危险按钮</van-button>

3. 【使用背景图】

注意：使用background-image属性设置背景图片时，需要使用网络图片或者base64格式，不支持本地路径