参考文档

引入 element.js¶

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

<script src="https://js.liquido.com/element-1.2.0.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.
verifyCard	Boolean(Optional)	控制是否在生成 card token 前验卡。

如果 verifyCard 设置为 true（或省略），在保存卡信息前会使用 0 元预授权来进行验卡（根据国家而定，也可能是一笔会自动退款的小额付款等）。

如果 verifyCard 设置为 false，保存卡信息时不会进行验卡。注意，之后必须在 30 分钟内通过一笔成功交易来确认卡的有效性。否则，card token 会在 30 分钟后失效。

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`
secureCvv	Boolean (Optional)	控制 `CVV` 显示方式。`true` 隐藏输入，`false` 显示明文。

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`。组件有值并且校验不通过才会返回 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`。只有当字段填写了足够长度但验证失败时，才会返回错误码。

错误码(number)	描述
1	组件还没有挂载完成
2	组件的值为空
3	组件的值格式校验不通过

由于 Error 只在特定条件下会返回，你可以使用在每个事件中都固定会返回的 complete 和 empty 这两个布尔值来手动校验组件的值。

Input validation¶

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

card.addEventListener('change', (event) => {
    const 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'
                }
            }
        });
    }
});