Skip to main content
Version: 3.x

TaroPlatformWeb

我们把编译时常用的逻辑抽象出了一个基类 TaroPlatformWeb,开发者可以继承于此基类,从而实现端平台的编译。

例如我们创建一个 H5 平台:

program.ts
import { TaroPlatformWeb } from '@tarojs/service'
export default class H5 extends TaroPlatformWeb {
// ...
}

方法与属性

constructor (ctx, config)

构造函数,接受两个参数。

参数类型说明
ctxobject插件上下文对象
configobjectTaro 编译配置

ctx

object

插件上下文对象。

this.ctx.modifyWebpackChain

获取 WebpackChain,例子:

program.ts
class H5 extends TaroPlatformWeb {
modifyWebpackChain() {
// 通过 this.ctx.modifyWepackChain 能获取到 WebpackChain 实例
this.ctx.modifyWebpackChain(({ chain }) => {
// chain.xxxx
})
}
}

helper

object

存放着一系列工具函数,对应 @tarojs/helper 包的导出内容。

config

object

编译配置对象。

(abstract) platform

抽象属性,子类必须实现。

string

平台名称,如:

program.ts
class H5 extends TaroPlatformWeb {
platform = 'h5'
}

(abstract) runtimePath

抽象属性,子类必须实现。

stirng | string[]

Web 端编译的运行时文件的解析路径,如:

program.ts
class H5 extends TaroPlatformWeb {
runtimePath = '@tarojs/plugin-platform-h5/dist/runtime'
}

setupTransaction

setup 阶段的事务钩子。

program.ts
class H5 extends TaroPlatformWeb {
/**
* 1. setupTransaction - init
* 2. setup
* 3. setupTransaction - close
* 4. buildTransaction - init
* 5. build
* 6. buildTransaction - close
*/
constructor (ctx, config) {
super(ctx, config)

this.setupTransaction.addWrapper({
init () {}
close () {}
})
}
}

buildTransaction

build 阶段的事务钩子。

program.ts
class H5 extends TaroPlatformWeb {
/**
* 1. setupTransaction - init
* 2. setup
* 3. setupTransaction - close
* 4. buildTransaction - init
* 5. build
* 6. buildTransaction - close
*/
constructor (ctx, config) {
super(ctx, config)

this.buildTransaction.addWrapper({
init () {}
close () {}
})
}
}

start ()

插件入口调用 start 方法开启编译,如:

program.ts
class H5 extends TaroPlatformWeb {
// ...
}

export default (ctx) => {
ctx.registerPlatform({
name: 'h5',
useConfigName: 'h5',
async fn({ config }) {
const program = new H5(ctx, config)
await program.start()
},
})
}

自定义平台类

接下来将以扩展对 Web 端的编译支持为例,介绍如何创建一个自定义平台类。

1. 继承基类

继承 TaroPlatformWeb 以实现 H5 类,并实现所有抽象属性、可选属性:

program.ts
import { TaroPlatformWeb } from '@tarojs/service'

const PACKAGE_NAME = '@tarojs/plugin-platform-h5'

class H5 extends TaroPlatformWeb {
// 平台名称
platform = 'h5'
// Web 端运行时文件的解析路径
runtimePath = `${PACKAGE_NAME}/dist/runtime`

constructor (ctx, config) {
super(ctx, config)

/**
* 1. setupTransaction - init
* 2. setup
* 3. setupTransaction - close
* 4. buildTransaction - init
* 5. build
* 6. buildTransaction - close
*/

// 可以在 setup 的不同阶段注入自定义逻辑
this.setupTransaction.addWrapper({
init () {}
close () {}
})

// 可以在 build 的不同阶段注入自定义逻辑
this.buildTransaction.addWrapper({
init () {}
close () {}
})
}
}

export default H5

2. 处理 API

在 Web 端环境中增减 API 其实并不难,在之前版本中开发者也可以通过配置为 @tarojs/taro 配置 alias 参数实现,在 @tarojs/plugin-platform-h5 中也是如此,通过将 runner 中相关的代码抽离实现的这一特性。

  modifyWebpackConfig () {
this.ctx.modifyWebpackChain(({ chain }) => {
const alias = chain.resolve.alias
alias.set('@tarojs/taro', require.resolve('./runtime/apis'))
})
}

虽然对 API 修改很容易,但是新增的 API 却不能通过 Taro.newAPI 的形式来使用,为此我们需要在插件打包时需要借助 exportNameOnly 插件输出当前插件支持的 API 列表。

rollup.config.js
import exportNameOnly from '@tarojs/plugin-platform-h5/build/rollup-plugin-export-name-only'
{
input: path.join(cwd, 'src/runtime/apis/index.ts'),
output: {
file: 'dist/taroApis.js',
format: 'cjs',
inlineDynamicImports: true
},
plugins: [exportNameOnly()]
}

并将 API 列表通过 babel-plugin-transform-taroapi 注册,帮助开发者将 Taro.newAPI 转换成对应语法使用。

  modifyWebpackConfig () {
this.ctx.modifyWebpackChain(({ chain }) => {
const rules = chain.module.rules
const script = rules.get('script')
const babelLoader = script.uses.get('babelLoader')
babelLoader.set('options', {
...babelLoader.get('options'),
plugins: [
[require('babel-plugin-transform-taroapi'), {
packageName: '@tarojs/taro',
apis: require(resolveSync('./taroApis'))
}]
]
})
})
}

3. 处理组件

使用 Taro 提供的组件仅仅需要在 runtime 中注册,并通过别名为不同前端 UI 框架配置所需的适配器(@tarojs/components/lib/[framework])。

import '@tarojs/components/dist/taro-components/taro-components.css'

import { applyPolyfills, defineCustomElements } from '@tarojs/components/loader'

// Note: 3.6.3 开始,不再需要手动调用 applyPolyfills 和 defineCustomElements
applyPolyfills().then(function () {
defineCustomElements(window)
})

如果需要新增组件可以考虑与 Taro 一样使用 stencil 或者其他 web-components 方案,当然也可以仅为单一框架提供组件库(例如 useHtmlComponents 模式,将组件库替换为 @tarojs/components-react)。需要注意的是,如果仅替换部分又不希望注册全部组件,可以手动注册所需组件并导出,比如 taro-pull-to-refresh 提供了下拉刷新的特性,如果未注册会导致相关特性无法使用。

src/runtime/index.ts
import { defineCustomElement } from '@tarojs/components/dist/components/taro-pull-to-refresh'

// Note: 3.6.3 开始,组件会自动注册,不需要手动调用 defineCustomElement
defineCustomElement()

对于下拉组件,也可以通过为 appConfig 新增 PullDownRefresh 配置替换使用,对于插件来说可以参考以下写法。

  modifyWebpackConfig () {
this.ctx.modifyWebpackChain(({ chain }) => {
chain.plugin('mainPlugin')
.tap(args => {
args[0].loaderMeta ||= {
extraImportForWeb: '',
execBeforeCreateWebApp: ''
}
args[0].loaderMeta.extraImportForWeb += `import { PullDownRefresh } from '@tarojs/components'\n`
args[0].loaderMeta.execBeforeCreateWebApp += `config.PullDownRefresh = PullDownRefresh\n`
return args
})
})
}