实现一个微信小程序组件库并发布到 npm

前言

微信小程序从基础库 2.2.1 版本开始支持使用 npm 方式安装第三方包，三年前我写过一个微信小程序组件库 Mind UI，但那时小程序还不支持 npm ，需要将组件库源码按需求拷贝到项目中使用，最近我对该组件库进行了升级，使其支持 npm 安装使用。
接下来我将尽可能详细的解析如何从零到一实现并发布一个微信小程序组件库。

一、准备

• 您应该有一些的微信小程序开发经验，了解如何实现一个简单的组件，了解微信开发者工具的使用；
• 简单了解微信官方文档的 开发第三方自定义组件；
• 简单了解微信官方提供的 小程序自定义组件开发模板；
• 了解 npm 的使用，了解 npm 网络问题的处理；

二、约定

• 本示例小程序名称为 weapp-demo-ui

三、安装官方模板

1. 创建项目文件夹
   在磁盘的合适位置创建项目文件夹并命名为 weapp-demo-ui (文件名随意，可与项目名无关);

2. 下载模板
   执行安装 小程序组件库模板 命令（全局安装，可在任意文件夹下执行）：

   npm install -g @wechat-miniprogram/miniprogram-cli
   

3. 初始化项目
   在 weapp-demo-ui 文件夹下，执行以下命令初始化项目模板：

   miniprogram init --type weapp-demo-ui
   

4. 命令行中模板选择 custom-component ，即初始化组件项目模板，敲回车键;

   

5. 接下来可以根据自己的需要填写对应项目的信息，也可以之后在 package.json 中修改；

   

6. 待模板文件生成后，运行以下命令安装项目依赖文件；

   npm install
   

四、目录结构介绍

完成以上步骤后，weapp-demo-ui 文件夹中会生成如下所示文件：

该文件夹下的主要目录结构与用处介绍如下，其中 miniprogram_dev 与 miniprogram_dist 分别为 dev 与 dist 命令生成，默认是没有的，且不需要作为 包文件发布到 npm。

├─ miniprogram_dev            // 开发环境构建目录，运行 `npm run dev` 生成
├─ miniprogram_dist           // 生产环境构建目录，运行 `npm run build` 生成
├─ node_modules               // 依赖文件
├─ src                        // 示例组件源码文件夹
├─ test                       // 测试用例
├─ tools                      // 构建相关代码
│   ├─ demo                   // 小程序示例目录，开发环境下会被拷贝生成到 miniprogram_dev 目录中
│   ├─ build.js               // 打包配置，一般不需要修改 
│   ├─ ...
│   └─ config.js              // 构建相关配置文件，需要做一些配置更改
├─ ...
├─ .gitignore                 // git commoit 时忽略的内容
├─ .npmignore                 // npm publish 时忽略的内容
├─ LICENSE                    // 组件库的开源协议
├─ gulpfile.js                // 组件打包配置
├─ package.json               // 项目信息与依赖等
└─ tsconfig.json              // TypeScript 编译器的配置文件

五、目录结构调整

我们将 src 与 tools/demo 中的示例文件清空，并按照以下目录形式实现自己的组件（组件的结构可以自己按需求调整，但需要与 config.js 中的配置对应上），以下以 button 组件为例：

├─ src                        
│   ├─ button                 // 按钮组件
│   │  ├─ index.wxml
│   │  ├─ index.js 
│   │  ├─ index.json
│   │  └─ index.wxss
│   ├─ ...                    // 其它组件  
│   └─ config.js              // 构建相关配置文件
│
├─ tool                       // 组件示例，与小程序项目目录一致
├─ demo                       // 组件示例，与小程序项目目录一致
│  ├─ pages                   
│  │  ├─ button               // 按钮示例页面
│  │  └─ ...                  // 其它示例页面
│  ├─ static                  // 图标等静态文件                   
│  └─ ...                          
├─ config.js

六、button 组件与示例的实现

组件库中组件的写法与项目中组件的实现一样，需要注意的是，在示例文件 pages/button 目录下的 index.json 文件中，button 组件的引入需要使用绝对地址 /components/button/index ，因为组件最终生成的文件，会存放到 components 文件夹中，并与 pages 目录同级。
关于 button 组件的实现，请访问我的组件库 mind-ui-weapp 中 button 源码。

// button 示例组件的引入，注意路径
{
  "navigationBarTitleText": "Button 按钮",
  "usingComponents": {
    "m-button": "/components/button"
  }
}

七、config.js 打包配置介绍

该文件是构建组件的配置文件，我们将需要构建的组件加入到 entry 配置项中：

// 省略代码
module.exports = {
  // 需要构建的组件
  entry: [
    'button/index'
  ]
  // ...
}
copy: ['./assets'],  // (src)目录下文件将会被复制到打包后的文件中，一般存放如全局样式、字体等静态文件
// 省略代码

八、组件预览

运行 npm run dev 命令，将会生成 miniprogram_dev 文件夹，使用微信开发者工具打开该文件夹，预览组件效果，如下图所示：

注意：修改 demo 文件夹下的文件，运行 npm run dev 不会被重新载入，需要手动删除 miniprogram_dev 文件后再运行，或者运行 npm run watch 命令监听该变更。

九、组件构建

运行 npm run build 命令，默认将会生成 miniprogram_dist 文件夹，该文件夹存放被构建后的组件，即为待发布的组件库文件。

十、发布到 npm

1. 注册/登录 npm 账号
   npm 官网：www.npmjs.com，此过程可能需要科学上网，注册过程略。

2. 命令行登录
   在项目目录下终端执行登录命令，根据提示输入刚注册的用户名、密码、邮箱即可登录。

    npm login
   

   注意

   • 登录时如果配置了全局淘宝镜像，需要将 npm 源设置会官方源；

     npm config set registry http://registry.npmjs.org
     

   • 登录时可能需要输入一次性密码，npm 会发邮件到刚才填入的邮箱中，从邮件中复制该一次性密码填入即可。

3. 发布到 npm
   执行发布命令

   npm publish
   

   • 执行 npm publish 后，登录时输入的邮箱将会收到一封 npm 发的一次性密码的邮件，有可能会提示将该密码输入到终端后才能发布成功。
   • 待发布成功后等几分钟，即可在 npm 官网上搜索到刚才发布的包。
   • 如果你使用的是 cnpm 安装该包，可能有一定的同步延迟时间，可以执行以下命名同步该包到 cnpm 镜像。

     cnpm sync <package>
     

十一、组件库应用

• 组件库安装
  在微信小程序项目的终端中执行命令安装该组件库（由于本示例组件并未发布，以下以我的 mind-ui-weapp 组件库替代）

  npm install mind-ui-weapp
  

安装后，项目的 node_modules 文件下将会生成该组件库，在微信开发者工具中选择 工具->构建 npm，将会在 miniprogram_npm 文件夹下生成可以被小程序中使用的组件包，如下图所示：

• 组件库使用
  在项目全局的 app.json 或者页面与组件的 .json 中，按需求引入组件即可使用，示例如下：

  "usingComponents": {
      "m-button": "mind-ui-weapp/button/index",
  }
  

至此，微信小程序组件库就创建完成了，我们可以根据需求添加更多的组件。

扩展

以下为 mind-ui-weapp 组件库的源码与使用文档，您可根据需求进行阅读：

组件库源码：github.com/NameLi/mind…
npm 包：www.npmjs.com/package/min…
使用文档：mind-ui-weapp.ixook.com