卡片信息展示

本页假定你已阅读安全元素概览——其中涵盖了铸造客户端令牌、加载 SDK 和样式化字段，这些内容在此同样适用。

在线查看

该演示会自行铸造令牌并自动挂载查看器。若展示按钮无响应，可使用Remint token & remount，并通过Reveal、Reveal CVV only或Mask尝试下文介绍的字段级控制。在单独标签页中打开 →

铸造展示令牌

调用POST /v1/client-token，传入"purpose": "reveal"以及你想展示的virtualCardId：

{
  "purpose": "reveal",
  "virtualCardId": "c107e50b-10f3-449c-92c0-609d9a8cfa2a"
}

将返回的clientToken和loadToken直接传递给下方的createCardViewer。

创建查看器

const viewer = createCardViewer({
  clientToken,
  loadToken,
  frameHostOrigin: "https://staging.secure.fluz.app",
  fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
});

fields控制按顺序渲染卡片的哪些部分——若省略，你将获得["pan", "expiry", "cvv"]。每一项要么是字段名本身，要么是一个{ field, individualReveal }对象；"pan"是{ field: "pan", individualReveal: true }的简写。仅支持pan、expiry和cvv这三个字段名——其他任何值都会在调用createCardViewer时同步抛出FluzElementsError（error.code === "INVALID_FIELD"），在你调用mount()之前就会报错。

Field	展示前的掩码占位符	说明
`pan`	`•••• •••• •••• {last4}`	后四位来自你的客户端令牌上的卡片元数据
`expiry`	真实的`MM/YYYY` —— 不做掩码	不视为敏感信息
`cvv`	`•••`	支持`individualReveal: false`（见下文）

individualReveal在每个字段上默认为true。将其设为false可阻止单独展示该字段——参见仅展示单个字段。它与reveal()相互独立，后者无论如何都会一次性展示所有字段。

挂载

await viewer.mount(document.getElementById("card-viewer"));

mount()会将每个已配置字段各自作为一个受沙盒限制的 iframe 追加到你传入的容器元素中——默认fields会生成三个独立的 iframe，而非一个合并的 iframe——并返回一个在所有 iframe 完成握手后才会 resolve 的 Promise。若出现以下情况会以FluzElementsError拒绝：

你传给createCardViewer的style未通过校验（error.code === "INVALID_STYLE"）——参见样式化字段
某个 iframe 未能在mountTimeoutMs内完成握手（error.code === "MOUNT_TIMEOUT"；默认 10 秒，可通过createCardViewer({ ..., mountTimeoutMs })配置）
某个 iframe 根本加载失败，或此查看器已被挂载（error.code === "MOUNT_FAILED"）——每个CardViewer实例只能挂载一次；如需再次挂载，请用createCardViewer创建新的实例

展示与掩码字段

await viewer.reveal(); // fetch and show every configured field at once
await viewer.reveal("cvv"); // fetch and show one field, if that field allows it
viewer.setMask("cvv", true); // re-mask a field that's already been revealed
viewer.setMask("cvv", false); // un-mask it again -- see below

reveal(field?)——异步。从 Fluz 获取真实值并展示。无参数调用时，无视individualReveal，一次性获取并展示所有已配置字段。传入字段名时，只获取并展示该字段——若该字段配置了individualReveal: false，则以error.code === "INDIVIDUAL_REVEAL_DISABLED"拒绝。未挂载的查看器，或字段名不在fields中，则以MOUNT_FAILED拒绝。
setMask(field, masked, options?)——同步、非异步。不会获取任何数据——仅切换当前展示状态：
- setMask(field, true)将字段恢复为占位符，无论此前是否展示过真实值。
- setMask(field, false)取消掩码——仅当该字段已被reveal()获取过真实值时才会展示真实值。若在任何reveal()之前调用，则字段仍保持占位符，因为尚无可展示的真实值。
- setMask(field, true, { hidden: true })会将字段完全清空（空白，连占位符也不显示），而非显示圆点/后四位/有效期。hidden仅在masked为true时生效。
- 不提供批量“全部掩码”的方法——若需重置整个查看器，请对fields中的每个字段分别调用setMask。
destroy()——销毁所有 iframe 并分离查看器。组件卸载时调用，以免在组件消失后仍遗留已挂载的 iframe。

仅展示单个字段

若只需单独展示某个字段（例如该字段旁边的“显示 CVV”按钮），调用reveal(field)即可——默认每个字段都允许此操作，因此常见场景无需额外配置。如果某个字段应当“绝不”单独展示，只能随整卡reveal()一同出现，可在fields中为其设置{ field, individualReveal: false }以选择退出：

const viewer = createCardViewer({
  clientToken,
  loadToken,
  frameHostOrigin: "https://staging.secure.fluz.app",
  fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
});

await viewer.reveal("cvv"); // rejects — error.code === "INDIVIDUAL_REVEAL_DISABLED"
await viewer.reveal(); // succeeds — reveals pan, expiry, and cvv together

针对选择退出的字段调用reveal(field)会在不联系frame-host的情况下以FluzElementsError（code: "INDIVIDUAL_REVEAL_DISABLED"）拒绝。无论如何，不带参数的reveal()总是会展示所有已挂载字段——individualReveal对其不起作用。

这是前端集成层面的选择，而非服务器强制的能力限制——它控制的是你的 UI 允许触发的行为，而不是授权可返回的数据范围。不要将individualReveal: false当作安全边界依赖。

处理事件

const unsubscribeMount = viewer.onMount(() => {
  // all configured fields have finished rendering
});

const unsubscribeError = viewer.onError((error) => {
  // error.code, error.message
});

onMount在每个已配置字段都在 iframe 内完成渲染后触发一次。onError用于接收已经挂载的 iframe 内部发生的问题——如reveal()失败或触发限流——而mount()或createCardViewer()本身的问题则会直接以拒绝或抛错的形式呈现（见下文）。onMount与onError均返回一个取消订阅函数。此能力可能产生的每个FluzElementsError及其出现位置：

Code	出现场景	含义
`INVALID_FIELD`	由`createCardViewer`抛出	某个`fields`项不是`pan`、`expiry`或`cvv`
`INVALID_FRAME_HOST_ORIGIN`	由`createCardViewer`抛出	`frameHostOrigin`不是已识别的 Fluz frame host
`INVALID_STYLE`	被`mount()`拒绝	某个`style`值校验失败
`MOUNT_TIMEOUT`	被`mount()`拒绝	某个字段的 iframe 未在`mountTimeoutMs`内完成握手
`MOUNT_FAILED`	被`mount()`拒绝，或由`reveal()` / `setMask()`抛出	某个 iframe 加载失败；查看器已被挂载；或对未挂载/未知字段调用了`reveal()` / `setMask()`
`INDIVIDUAL_REVEAL_DISABLED`	被`reveal(field)`拒绝	该字段配置了`individualReveal: false`
`FIELD_ERROR`	发送给`onError`	挂载后在 iframe 内部发生的`reveal()`失败（网络错误，或尚未允许展示）
`RATE_LIMITED`	发送给`onError`	此授权的展示尝试过多——`error.message`包含重试等待时间

完整示例

<div id="card-viewer"></div>

<script src="https://secure-cdn-staging.fluz.app/secure-elements/v0.1.0/index.global.js"></script>
<script>
  (async () => {
    const { createCardViewer } = FluzSecureElements;

    const res = await fetch("/mint-reveal-token", { method: "POST" });
    const { clientToken, loadToken } = await res.json();

    const viewer = createCardViewer({
      clientToken,
      loadToken,
      frameHostOrigin: "https://staging.secure.fluz.app",
      fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
      style: {
        fontFamily: "IBM Plex Mono",
        fontSize: "16px",
        color: "#1a1a1a",
      },
    });

    viewer.onError((error) => console.error(error.code, error.message));
    viewer.onMount(() => console.log("card viewer ready"));

    await viewer.mount(document.getElementById("card-viewer"));
  })();
</script>

/mint-reveal-token是你自有的后端路由——它会使用你的 Fluz OAuth 访问令牌调用POST /v1/client-token，详见铸造客户端令牌。

后续步骤

安全元素概览

令牌铸造、SDK 加载、样式化与 CSP。

在线演示

展示、仅展示 CVV 与掩码，运行于 staging。

示例集成

可运行的纯 HTML 与 React 展示示例，含令牌铸造服务器。

​在线查看

​铸造展示令牌

​创建查看器

​挂载

​展示与掩码字段

​仅展示单个字段

​处理事件

​完整示例

​后续步骤

安全元素概览

在线演示

示例集成

在线查看

铸造展示令牌

创建查看器

挂载

展示与掩码字段

仅展示单个字段

处理事件

完整示例

后续步骤