@tarojs/o2h5-taro-blended

@tarojs/o2h5-taro-blended

在原生项目的分包中使用一个完整的 Taro NEXT 项目，开发 Taro 互动双端项目需要使用此插件

💡功能

• 雪碧图：对指定文件夹内的图片进行雪碧图的合成，并根据对应路径对雪碧图进行命名。
• 图片压缩：能对制定文件夹内的图片进行压缩处理，能普遍减少图片 70% 的大小。
• 上传文件：能将项目打包后的静态文件自动上传到 CDN 中。
• 图片缓存：对已上传的图片进行了缓存处理，已经上传的图片不会再进行压缩和上传操作。
• 引用路径替换：能智能地替换代码中的静态资源的引用路径，包括但不限于 JS、CSS、雪碧图和非雪碧图资源。
• 添加公共逻辑的引用基础：打通京东购物小程序公共方法、组件和基类的引用基础，使开发者通过简单的 alias 即可进行逻辑的引用。
• 打包文件自动迁移：对 Taro 打包后的小程序文件进行自动迁移，迁移到配置的目录文件夹下。
• 补齐 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 模式生效。