@tarojs/o2h5-taro-blended
在原生项目的分包中使用一个完整的 Taro NEXT 项目,开发 Taro 互动双端项目需要使用此插件
💡 功能
- [x] 雪碧图:对指定文件夹内的图片进行雪碧图的合成,并根据对应路径对雪碧图进行命名。
- [x] 图片压缩:能对制定文件夹内的图片进行压缩处理,能普遍减少图片 70% 的大小。
- [x] 上传文件:能将项目打包后的静态文件自动上传到 CDN 中。
- [x] 图片缓存:对已上传的图片进行了缓存处理,已经上传的图片不会再进行压缩和上传操作。
- [x] 引用路径替换:能智能地替换代码中的静态资源的引用路径,包括但不限于 JS、CSS、雪碧图和非雪碧图资源。
- [x] 添加公共逻辑的引用基础:打通京东购物小程序公共方法、组件和基类的引用基础,使开发者通过简单的 alias 即可进行逻辑的引用。
- [x] 打包文件自动迁移:对 Taro 打包后的小程序文件进行自动迁移,迁移到配置的目录文件夹下。
- [x] 补齐 Taro 编译短板:通过添加拓展配置项,使 Taro 可以额外编译配置项中的第三方依赖。
安装
在 Taro 项目根目录下安装
$ yarn add @tarojs/o2h5-taro-blended --registry=http://registry.m.jd.com
使用
引入插件
请确保 Taro CLI 已升级至 Taro 3.3.8+
的最新版本。
建议将版本稳定在3.3.8,因为后续的一些版本中,Taro 可能对 webpack 的配置进行了修改,有可能会影响插件功能的使用
修改项目 config/index.js
中的 plugins 配置为如下
const config = {
...
plugins: [
['@tarojs/o2h5-taro-blended', {
compressPic: true,
uploadToOSS: {
version: '1.0.0',
projectName: 'my-first-project',
access: 'xxx',
secret: 'yyy',
},
moveToWeapp: {
destPath: path.join(__dirname, '../../wxapp/pages/testMini')
}
}]
]
...
}
项目图片
在 Taro 互动项目中,我们将图片区分成两种类型,雪碧图图片和非雪碧图图片,并统一放置在对应的文件夹下。
使用规范和方法【必看】:
- 每个页面的雪碧图需放在页面的根目录下的
sprite
文件夹,如当前页面为src/pages/index
,则需要新建src/pages/index/sprite
文件夹。 - webpack 会通过读取
sprite
文件夹内不同的二级文件夹的图片来生成对应的雪碧图(拗口)。 举个例子,当前sprite
文件夹内有『0』『1』『2』三个文件夹: 因此在执行构建后,会生成三张雪碧图,这些雪碧图会生成在src/img
文件夹中: 生成的雪碧图命名规则为:sprit.{页面路径}.{二级文件夹名称}.png
若发现不符合命名规则的雪碧图,请检查自身雪碧图源文件路径是否符合上述规则 - 除了雪碧图源文件摆放的位置有规定之外,雪碧图的引用也有对应的规则,同一个二级文件夹下的雪碧图源文件规定只能被同一个
.scss
所引用,否则有可能会出现生成的雪碧图缺失部分图片的问题。【这点请千万注意!!!!】 若有特殊情况不能按照上述规则引用,请不要使用雪碧图。 - 在生成了雪碧图之后,webpack 会通过插件将这些源文件上传到 CDN 中,并对样式文件中的路径进行替换,换而言之,开发者只需按照上述规则摆放好源文件,并按照一定的规范进行引入即可。其余操作基本自动化。
关于非雪碧图文件
若使用的图片为非雪碧图文件,则需要在页面的根目录下新建 nosprite
文件夹,然后将非雪碧图图片置于文件夹中引用即可,如当前页面为 src/pages/index
,则需要新建 src/pages/index/nosprite
文件夹,并将非雪碧图放置于该文件夹中。在打包过程中,会自动将这些非雪碧文件进行 CDN 的上传,并对 SCSS 文件中的引用路径进行处理。
图片缓存
在每次进行打包 build 操作的时候,插件会在项目的根目录维护一份 image-cache.js
文件,这份文件作为已上传图片的缓存记录。当下一次再进行 build 操作的时候,我们会读取这份文件,判断当前 build 操作下涉及的图片有没有是在缓存记录中的,然后只压缩和上传不在记录中的文件,并将这些文件名新增在缓存记录中。
而项目的图片我们统一使用了内容哈希来进行命名,因此只有当图片的内容发生了变化,图片的命名才会产生对应的改变,保证了图片缓存记录的可用性。
配置项详解
imgLimit
boolean | number
默认值: false
同 url-loader
的 limit
字段的功能
imgQuality
number
默认值: ``
在 JFS 图片后添加质量控制参数
isUseWebp
boolean
默认值: false
该功能在非 MAC 系统上不可用
是否开启 webp
功能,注意只针对 jpg/jpeg
图片,因为 png
已使用 tinyPng
进行压缩,再进行 webp
转换图片体积有可能反而会变大。
useInlinePack
boolean
默认值: false
是否开启离线包功能,开启后,所有资源都会变成相对路径来进行引用,且图片会关闭缓存功能,每次都会进行重新压缩。
compressPic
boolean
默认值:false
是否开启图片压缩功能,仅在生产环境有效。
extraComplierList
注意,该配置只适用于开发模式,生产模式已更新为打包时对所有第三方依赖进行编译
为了兼顾开发模式的编译速度和保证编译后的代码不产生报错,才提供了该配置项
string[]
默认值:[]
配置需要额外编译的第三方依赖
useHybrid
boolean
默认值:false
是否开启 hybrid 功能,开启后,所有生成的图片中带有 jdhybrid
关键字的图片都会自动添加上 ?jdhybrid-offline=1
参数。
preloadKeyword
string
默认值: ''
通过输入需要进行 preload 的图片关键字,当 blended 插件在识别到加载的图片中包含这个关键字时,会收集这些图片的 CDN 地址,并输出文件名为 preloadList.js
的预加载列表文件到项目根目录。当输入的 preloadKeyword 为 false 值时,blended 插件将不会输出预加载列表文件。
preloadDefaultList
string[]
默认值: '[]'
默认的预加载列表
preloadIgnoreList
preloadIgnoreList.h5
string[]
默认值: '[]'
H5环境下,preload 列表生成时需要过滤的字符串列表
preloadIgnoreList.weapp
string[]
默认值: '[]'
微信小程序环境下,preload 列表生成时需要过滤的字符串列表
cdnDomain
CDN 一级域名配置,目前仅支持非图片的静态资源和图片资源的 CDN 一级域名的配置
cdnDomain.staticDomain
string
默认值:m
非图片资源的 CDN 一级域名配置
cdnDomain.imgDomain
string
默认值:storage
图片资源的 CDN 一级域名配置
moveToWeapp
将 Taro 打包后的小程序文件自动移入原生小程序项目下的配置
moveToWeapp.destPath
string
默认值:''
计划移入的原生小程序项目页面的绝对路径
moveToWeapp.identity
string
默认值:''
这个值用于改变 webpack 输出的 jsonpFunction 的值,避免在同一个原生项目下,不同 Taro 项目的 chunk 加载的冲突
uploadToOSS
上传 JS、CSS、和图片等静态资源到 OSS 上,上传的目录结构为:{projectName}/{version}/{资源文件}
uploadToOSS.access
string
默认值:``
OSS 上传的 access key
uploadToOSS.secret
string
默认值:``
OSS 上传的 secret key
uploadToOSS.projectName
string
默认值:``
OSS 上传文件夹的第一层级目录名
uploadToOSS.version
string
默认值:``
OSS 上传文件夹的第二层级目录名
uploadToOSS.isPrivate
boolean
默认值:false
这个配置将决定对静态资源进行引用时,是使用对外的域名还是对内的域名;若开启,则使用域名 storage.360buyimg.com
,若不开启,则使用 storage.jd.com
uploadToOSS.uploadJSAndCSS
boolean
默认值:true
是否同时上传打包后的 JS 和 CSS,默认开启,这个配置仅针对 H5 模式生效。