Skip to content

Latest commit

 

History

History
287 lines (196 loc) · 8.13 KB

api.md

File metadata and controls

287 lines (196 loc) · 8.13 KB
Raw

接口

behavior(definition)

注册并返回 behavior 对象。

definition

behavior 定义对象，支持字段和小程序 Behavior 构造器参数一致。

const behavior = simulate.behavior({
    /* 小程序 behavior 支持的定义段 */
});

load(componentPath, tagName, options) / load(definition)

加载自定义组件，返回 componentId。加载方式有两种，一种是传入自定义组件的路径，另一种是传入自定义组件的定义对象。

componentPath

自定义组件所在绝对路径。

const id = simulate.load('/path/to/component')

tagName

可选字段，当自定义组件被实例化后对应的 dom 节点的标签名。如果不传此字段则默认为 main。

const id = simulate.load('/path/to/component', 'custom-comp')
const comp = simulate.render(id)

console.log(comp.dom.tagName) // 此处会输出 CUSTOM-COMP

options

可选字段，加载自定义组件时传入的一些配置参数，支持如下字段：

属性名 类型 默认值 描述
compiler String official wxml 编译器类型，传入 official 表示使用官方编译器，传入 simulate 表示使用 js 实现的模拟编译器
compilerOptions Object 编译配置，当 compiler = official 时生效
rootPath String 组件所在目录 项目根路径，用于编译组件相关模板，要求组件所有依赖在此目录下，不传则取当前组件所在目录作为其值
less Boolean false 自定义组件的 wxss 是否需要经过 less 编译
usingComponents Object undefined 使用到的自定义组件映射表，会将传入组件申明的 usingComponents 覆盖

PS：在使用 karma 测试时只支持官方编译器编译 wxml 文件，不支持使用 js 模拟的编译器，因此就算在 simulate.load 方法中配置了 compiler: 'simulate' 也不会生效。

// 不传 tagName
const id1 = simulate.load('/path/to/component', {
    rootPath: 'path/to/component/dir'
})
// 传 tagName
const id2 = simulate.load('/path/to/component', 'custom-comp', {
    rootPath: 'path/to/component/dir'
})

compilerOptions

使用官方编译器时传入的编译配置

属性名 类型 默认值 描述
maxBuffer Number 1024 * 1024 执行编译时输出缓存区大小
wxmlList Array<String> rootPath 下需要编译的 wxml 文件，默认取 rootPath 下所有 wxml 文件
wxsList Array<String> rootPath 下需要编译的 wxs 文件，默认取 rootPath 下所有 wxs 文件

definition

自定义组件的定义对象，除了小程序本身支持的字段外，额外支持字段如下：

属性名 类型 描述
id String 可选字段，如果传了此字段，则表明注册为全局组件，其他组件可直接在 template 中使用而无需在 usingComponents 里引入
tagName String 可选字段，指定组件对应的 dom 节点的 tagName，默认取 usingComponents 里的定义或组件自身的 id
template String 组件模板，即组件对应的 wxml 内容
usingComponents Object 使用到的自定义组件映射表，子孙组件在进行 usingComponents 处理时，会从此表寻找同名组件进行覆盖处理，支持传入覆盖路径或者组件 id
behaviors Array behavior 的用法和小程序类似
options Object 配置对象，支持小程序自定义组件 options 定义段支持的所有字段
options.classPrefix String 组件样式的私有化前缀，默认是空串，即没有前缀 
simulate.load({
    id: 'view',
    tagName: 'wx-view',
    template: '<div><slot/></div>'
}); 

let childId = simulate.load({
    tagName: 'xxx',
    template: '<view><slot/></view>', // 直接使用全局组件
});

let id = simulate.load({
    template: '<child>123</child>',
    usingComponents: {
        'child': childId, // 声明要使用的组件，传入组件 id
    },
    behaviors: [behavior],
    options: {
        classPrefix: 'xxx',

        /* 其他小程序自定义组件支持的 option，比如 addGlobalClass 等 */
    },

    /* 其他小程序自定义组件支持的定义段，比如 methods 定义段等 */
});

render(componentId, properties)

渲染自定义组件，返回 RootComponent。

componentId

调用 load 接口返回的 id。

properties

可选字段，创建组件实例时，由组件接收的初始 properties 对象。

const rootComp = simulate.render(id)

match(dom, html)

检查 dom 节点的内容是否符合给定的 html 结构，通常用于比较渲染结果是否符合预期。

const isMatch = simulate.match(dom, '<view>123</view>')

async sleep(timeout)

延迟一定时间执行后续代码，主要用于处理需要等待一定时间才能往后续进行操作的情况。此方法会返回一个 promise 对象。

await simulate.sleep(300) // 等待 300ms 后再继续后续代码的执行

scroll(component, destOffset, times, propName)

模拟元素滚动。destOffset 为滚动的目标数值；times 为触发 scroll 事件的次数，默认为 20 次；propName 为滚动字段，默认为 scrollTop。

PS：在真实浏览器环境下 times 无效，具体 scroll 事件的触发次数取决于浏览器自身的实现。

simulate.scroll(component, 100, 15) // 纵向滚动到 scrollTop 为 100 的位置，期间会触发 15 次 scroll 事件

Class: Component

组件。

属性

属性名 类型 描述
dom Object 组件实例对应的 dom 节点
data Object 组件实例对应的 data 对象
instance Object 组件实例中的 this，通过此字段可以访问组件实例的 methods 等定义段

方法

querySelector(selector)

获取符合给定匹配串的第一个节点，返回 Component 实例。

PS：支持 selector 同小程序自定义组件的 selectComponent 接口

const childComp = comp.querySelector('#a')

querySelectorAll(selector)

获取符合给定匹配串的所有节点，返回 Component 实例列表

PS：支持 selector 同小程序自定义组件的 selectAllComponents 接口

const childComps = comp.querySelectorAll('.a')

setData(data, callback)

调用组件实例的 setData 方法.

comp.setData({ text: 'a' }, () => {})

dispatchEvent(eventName, options)

用于模拟触发该组件实例节点上的事件。

// 触发组件树中的节点事件
comp.dispatchEvent('touchstart', {
  touches: [{ x: 0, y: 0 }],
  changedTouches: [{ x: 0, y: 0 }],
})

// 触发组件树中的节点自定义事件
comp.dispatchEvent('customevent', {
  touches: [{ x: 0, y: 0 }],
  changedTouches: [{ x: 0, y: 0 }],
  /* 其他 CustomEvent 构造器支持的 option */
})

addEventListener(eventName, handler, useCapture)

用于外部监听组件触发的事件。

comp.addEventListener('customevent', evt => {
    console.log(evt)
})

removeEventListener(eventName, handler, useCapture)

用于外部取消监听组件触发的事件。

const handler = evt => {
    console.log(evt)
    comp.removeEventListener('customevent', handler)
}
comp.addEventListener('customevent', handler)

triggerLifeTime(lifeTime, args)

触发组件实例的生命周期钩子。

comp.triggerLifeTime('moved', {test: 'xxx'})

triggerPageLifeTime(lifeTime, args)

触发组件实例中配置的页面的生命周期钩子。

comp.triggerPageLifeTime('show', {test: 'xxx'})

toJSON()

将节点组件下的节点树生成一个 JSON 树

comp.toJSON()

Class: RootComponent

根组件，继承自 Component。亦即是说，所有 Component 支持的属性/接口，RootComponent 都支持。

方法

attach

将根组件实例挂载在传入的 dom 节点上。

const parent = document.createElement('div')
rootComp.attach(parent)

detach

将根组件实例从父亲 dom 节点上移除。

rootComp.detach()