参考文档

引入element.js

当你使用element.js, 你应当永远从我们托管的地址引入element.js: https://js.liquido.com/element.js. 测试环境可以使用下面的地址https://js.dev.liquido.com/element.js.

<script src="https://js.liquido.com/element.js"></script>

Liquido 对象

liquido()
liquidoInstance.elements()
liquidoInstance.createToken()

创建一个Liquido实例

const liquidoInstance = liquido('your_api_key')

创建一个elements实例

创建一个预构建的UI组件去收集用户的信用卡信息.

const elements = liquidoInstance.elements({ 
    locale: 'en',
    country: 'BR'
})

这个方法创建一个 elements 实例, 管理了一系列的元素. 它能接受一个 options 对象. 可用的options参数如下:

可选项	类型	描述
locale	String	The IETF language tag of the locale to display placeholders and error strings in. Default is Spanish (en). Supported values are: en, es, pt.
country	String	User’s country code. ISO 3166-1 alpha-2 codes.
fonts	Array (Optional)	An array of custom fonts, which Elements created from the elements object can use. Fonts can either be loaded via a CSS file by passing an object with the cssSrc attribute, or they can be loaded directly by passing a Font object.

cssSrc 属性

Parameter	Type	Description
cssSrc	String	A relative or absolute URL pointing to a CSS file with @font-face definitions.

Font 对象

参数	类型	描述
family	String	The name to give the font.
src	String	A valid src value pointing to your custom font file. This is usually (though not always) a link to a file with a .woff, .otf, or .svg suffix.
display	String(Optional)	A valid font-display value.
style	String	A valid font-style value. Defaults to 'normal'.
unicodeRange	String(Optional)	A valid unicode-range value.
weight	String(Optional)	A valid font-weight. Note that this is a string, not a number.

创建一个 card token

使用 liquidoInstance.createToken 方法把表单收集的信息转化成一个card token.

liquidoInstance.createToken(card, tokenData)
    .then((result) => {
      // Handle Token (result.data.cardId)
    })
    .catch((result) => {
      // Handle result.error
    })

这个方法有2个参数.

element, 你希望标记化表单信息的element对象. 如果适用, element会从你的实例上提交表单数据到liquido的服务器进行标记化.
tokenData, 包含您可能已收集的其他付款信息的对象. 对于信用卡，它可以包含以下参数:

参数	类型	描述
name	String	Cardholder name.
email	String(Optional)	email address.

liquidoInstance.createToken 返回一个 Promise 处理 result 对象. 这个对象可以是下面2种情况:

result.data: 成功创建card token.
result.error: 一个error, 包含校验异常信息.

result.data 包含如下参数:

{
    "cardId": "3f4b0d0f-297e-4b2d-94f3-7e80e5d024e9",  // card token which need to send to server.
    "card": {                                          // card info
        "cardHolderName": "HolerName",                 // card holder name     
        "expirationMonth": 11,                       
        "expirationYear": 2026,
        "brand": "VISA",                        
        "bin": "411111",                               // Top 6 digits of card number
        "last4": "1111"                                // Last 4 digits of card number
    }
}

Elements 对象

elements.create()
element.mount()
element.addEventListener()
Other methods

elements.create(type, options)

const card = elements.create('card')

该方法创建一个指定类型的Element对象. 可用的类型如下:

类型	描述
card	A flexible single-line input that collects cardNumber, cardExpiration and cardCvc.
pan	The card‘s number. Use alongside the `expiration` and `cvv` Elements.
expiration	The card‘s expiration date. Use alongside the `pan` and `cvv` Elements.
cvv	The card‘s CVC number. Use alongside the `pan` and `expiration` Elements.

支付表单样例

使用 card Element的样例

使用pan, expiration, 和cvv Elements的样例

Element Options

所有的Elements 接收一个通用的options.

可选项	类型	描述
placeholder	String or Object	设置Element的placeholder. 当Elements为 `pan`,`expiration`或者`cvv`时该选项为对应 placeholder 值的字符串. 当Elements为`card`时, 该选项为包含对应每个 input placeholder 值的对象: `{` `cvv: "cvv placeholder",` `pan: "number placeholder",` `expiration: "expiration placeholder"` `}`
classes	Object (Optional)	自定义容器 DOM 元素在不同特定状态下的类名. - `base` - 提供给容器的基础类名. 默认为LiquidoElement. - `complete`- 用户在Element上输入完成时提供给容器的类名. 默认为LiquidoElement--complete. - `empty` - 当Element值为空时提供给容器的类名. 默认为LiquidoElement--empty. - `focus` - 当Element获取焦点时提供给容器的类名. 默认为LiquidoElement--focus. - `invalid` - 用户在Element上的输入值校验不通过时提供给容器的类名. 默认为LiquidoElement--invalid.
style	Object (Optional)	使用 CSS 属性自定义 Element 的样式. 样式可以通过下列对象进行定义. - `base`, 基础样式 - 所有其它状态的样式都会继承这个样式. - `complete`, 当Element的值校验通过时提供给Element的样式. - `empty`, 当Element的值为空时提供给Element的样式. - `invalid`, 当Element的值校验不通过时提供给Element的样式. 对于上面的每一个状态，都有以下的样式可以自定义. - `color` - `fontFamily` - `fontSize` - `fontStyle` - `lineHeight`, 为了避免光标在浏览器之间呈现不一致，请考虑在元素的容器上也使用该属性. - `letterSpacing` 以下伪类和伪元素也可以作为嵌套对象使用上述属性进行样式设置. - `:hover` - `:focus` - `::placeholder`

element.mount(domElement)

你需要一个DOM容器挂载element实例.

调用element.mount() 方法把element实例挂载到DOM. element.mount() 可以接收一个css选择器(例如: '#card-element')或者一个DOM元素.

card.mount('#form-item__card')

element.addEventListener(event, handler)

和你的Element通讯的唯一方法就是监听event. element会emit以下任何event. 所有event都有一个有效负载对象，该对象具有element属性，该属性具有发出event的element的类型。

Event	描述
blur	当任意 elements 失去焦点时触发. 事件有效载荷始终包含某些特定的键: `empty` - Boolean - `true`代表值为空. `complete` - Boolean - `true`代表值的格式正确且填写完整. `complete`可用于逐步展示表单的下一部分或启用表单提交. `complete`不是客户是否完成输入的指示 - 它仅表示该字段已包含完整, 格式正确的值. `error` - 当前数据存在验证错误, 包含由`message`, `code`, 和 `element`组成的`validation_error`. `element` - String - 触发此事件的Element名称: `pan`, `expiration`, `cvv`. `hasFocus` - Boolean - `true`表示任意Field元素具有焦点(在下列Fields中此值总为False:`pan`, `expiration`和`cvv`).
focus	当任何Fields元素获得焦点时触发。事件有效载荷始终包含某些特定的键: `empty` - Boolean - `true`代表值为空. `complete` - Boolean - `true`代表值的格式正确且填写完整. `complete`可用于逐步展示表单的下一部分或启用表单提交. `complete`不是客户是否完成输入的指示 - 它仅表示该字段已包含完整, 格式正确的值. `error` - 当前数据存在验证错误, 包含由`message`, `code`, 和 `element`组成的`validation_error`. `element` - 触发此事件的Element名称: `pan`, `expiration`, `cvv`.
error	检测到客户端验证错误时触发. 事件有效载荷包含具有当前验证错误信息的error. `validation_error`由以下内容组成: `message`, `code`和`element`.
complete	当Element完整状态变化时触发. 事件有效载荷总是包含`complete` - Boolean - key, 当字段完整且格式正确时为`true`, 否则为`false`.
empty	当Element是否为空值的状态变化时触发, 事件有效载荷总是包含`empty` - Boolean - key, 当Field为空时该值为`true`, 否则为`false`.
ready	当Element安装并加载到DOM中时触发.
change	当字段上的任何以下值发生更改时触发. 除了一些特定于字段的键之外, 事件有效负载始终还包含某些特定的键. `empty` - Boolean - `true`代表值为空. `complete` - Boolean - `true`代表值的格式正确且填写完整. `complete`可用于逐步展示表单的下一部分或启用表单提交. `complete`不是客户是否完成输入的指示 - 它仅表示该字段已包含完整, 格式正确的值. `error` - 当前数据存在验证错误, 包含由`message`, `code`, 和 `element`组成的`validation_error`.

Input validation

Elements会校验用户输入. 为了帮助您捕获错误, 请监听Element的 change 事件并显示返回的错误:

card.addEventListener('change', (event) => {
  var errorEl = document.getElementById('form-item__error--card')
  errorEl.textContent = event.error
      ? event.error.message
      : ''
})

其他方法

方法	描述
blur()	让Element失去焦点.
clear()	清空ELement.
destroy()	从DOM移除element并销毁. 注意: 销毁后的element无法重新激活和挂载到DOM.
focus()	Element获得焦点. 在`card` Element 焦点会转移到`pan`输入框.
unmount()	从DOM反挂载element. 调用`element.mount()`方法可以重新挂载到DOM.
update(options)	更新Elements的可选项. 和`elements.create()`方法的options可用参数一致.

Element可以通过 update() 方法动态更新样式. 这种方法可以用来模拟CSS media 查询，当在不同的设备上查看时，这些查询会自动调整元素的大小.

window.addEventListener('resize', (event) => {
  if (window.innerWidth <= 320) {
    card.update({
        style: {
            base: {
                fontSize: '13px'
            }
         }
      })
  } else {
    card.update({
        style: {
            base: {
                fontSize: '16px'
            }
         }
     })
  }
})