# um-pack

**Repository Path**: leopord-lau/um-pack

## Basic Information

- **Project Name**: um-pack
- **Description**: 基于uniapp的微信小程序解耦构建方案
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-12-06
- **Last Updated**: 2023-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# um-pack

基于uniapp微信小程序的解耦构建方案。

**该库仅适用于使用脚手架搭建的uniapp项目**

## 功能
- 支持原生页面直接在uni-app项目中使用
- 支持原生小程序项目直接在uni-app项目中进行开发
- 支持uni-app项目调用原生小程序项目中的资源
- 支持极端方式将uniapp项目与主包进行合并
- 支持在uni的vue文件中引入原生主小程序或者wxResource目录中的wxs


## 搭建uniapp项目

```shell
vue create -p dcloudio/uni-preset-vue projectName
```

具体详情请看 [通过vue-cli命令行](https://uniapp.dcloud.net.cn/quickstart-cli.html#install-vue-cli)


## 安装

在搭建好uniapp项目后安装 um-pack

```shell
npm install um-pack
```

## 使用

### 初始化

```shell
um-pack --init
```

将在项目根目录下生成一个umPackConfig.js文件，并更新package.json，添加um-pack启动命令。

### 构建

在执行了 `um-pack --init`命令后，可以看到package.json文件中多了 `pack:build`、`pack:dev` 两个命令


```shell
npm run pack:dev
npm run pack:build
```

## 配置

umPackConfig.js

```json
{
  // 主包目录
  "mainPackagePath": null,
  // 合并模式, 可选（relegation、top、main）
  // 默认relegation，将uni项目作为分包合并到主包中
  // top: 将uni项目作为子目录合并到主包当中，存在冲突以主包为主
  // main: 将uni项目作为主包进行处理，不处理mainPackagePath字段中定义的主包
  // 当不存在主包时，该字段会自动更改成main
  "packMode": "relegation",
  // uni项目打包构建后放置的目录名
  "subPackagePath": "subPackage",
  // uni项目的代码放置目录
  "uniCodePath": "src",
  // project.config.json文件放置目录，null代表使用默认值，默认为根目录
  "projectConfigPath": null,
  // uni项目中的原生资源目录路径，默认值为 'src/wxResource'
  "wxResourcePath": "wxResource",
  // 原生资源目录路径别名, null代表使用默认值，默认值为 @wxResource
  "wxResourceAlias": "@wxResource",
  // 引用原生资源的js的特殊API名称设定, null代表使用默认值，默认值为 __uniRequireWx
  "uniRequireApiName": "__requireWxJs",
  // 引用原生资源的样式文件的特殊API名称设定, null代表使用默认值，默认值为 __requireWxss
  "uniImportWxssApiName": "__requireWxss",
}
```

### packMode

- relegation: 将uni项目作为分包合并到主包中
- top:  将uni项目作为子目录合并到主包当中，存在冲突以主包为主
- main: 将uni项目作为主包进行处理，不处理mainPackagePath字段中定义的主包


### wxResource相关配置

当uniapp项目存在原生资源时，可以在uniapp项目中通过以下方法引入原生资源：

#### 引入js

```js
__requireWxJs("@wxResource/index.js");
```

#### 引入wxss

```css
__requireWxss {
  import: "@wxResource/index.wxss";
}
```

#### 使用页面

需要先在src/pages.json文件定义路由

```json
  "wxResource": {
		"pages": [
			"pages/index/index"
		]
	}
```

在构建后会作为 uniapp 项目中的页面，并自动添加到app.json中的pages字段中：

```json
  "pages": [
    "pages/index/index",
    "wxResource/pages/index/index"
  ],
```

在 pages/index/index 文件使用：

```js
wx.navigateTo({
  url: "/wxResource/pages/index/index",
});
```


> 注册小程序。接受一个 Object 参数，其指定小程序的生命周期回调等。
> App() 必须在 app.js 中调用，必须调用且只能调用一次。不然会出现无法预期的后果。

## 示例

### 示例1

example/um-pack-01

此示例是与主包进行合并的示例，主包可以是通过微信开发者工具创建的原生项目，也可以是uniapp打包后的dist包。

**nativeProject**: 原生项目
**uniappProject**: uniapp项目打包后的dist包

通过更改 umPackConfig 文件的 mainPackagePath 字段来实现打包不同的主包。

### 示例2

example/um-pack-02


此示例是将uniapp项目作为主包进行处理，同时使用了wxResource这个原生项目中的文件。

#### 配置

在umPackConfig.js文件中配置相关字段：

```json
  wxResourcePath: "wxResource",
  wxResourceAlias: "@wxResource",
  uniRequireApiName: "__requireWxJs",
  uniImportWxssApiName: "__requireWxss",
```


#### 使用

wxResource仅支持在uniapp项目中使用，主包并不支持。

##### 使用js文件

```js
let { formatTime } = __requireWxJs("@wxResource/utils/util.js");
```

##### 使用 wxss 文件

```css
__requireWxss {
  import: "@wxResource/static/index.wxss";
}
```

##### 使用wxs文件

```html
<view>
  <wxs module="m1">
    var module1 = __requireWxJs("@wxResource/static/index.wxs");
		module.exports.msg = module1.msg;
  </wxs>
  <view>{{ m1.msg }}</view>
</view>
```

##### 使用页面

要想使用 wxResource 中页面，需要在 uniapp 项目中的 pages.json 文件中进行处理。

```json
  "wxResource": {
		"pages": [
			"pages/index/index"
		]
	}
```

在构建后会作为 uniapp 项目中的页面，并自动添加到app.json中的pages字段中：

```json
  "pages": [
    "pages/index/index",
    "wxResource/pages/index/index"
  ],
```

**注意，当存在主包时，wxResource将作为uniapp项目的子目录，而不是一个独立分包**

### 示例3

example/um-pack-03

本示例是 packMode 为 top 的情况，会把 uniapp 项目作为子目录放入主包下，同时将 uniapp 项目中的分包同时打包进主包中，不作为分包使用。