# @column-na/card-reveal-react-native 中文文档 规范地址：https://npmcn.com/package/%40column-na/card-reveal-react-native/ 版本：0\.13\.0 npm 元数据更新时间：2026-10-31T05:06:19.353Z 中文译文更新时间：2026-11-10T14:18:24.511Z 软件包许可：SEE LICENSE IN LICENSE 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40column-na/card-reveal-react-native 原文对照：https://npmcn.com/package/%40column-na/card-reveal-react-native/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：93.7 kB，6 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：react \>=19\.1\.0，react-native \>=0\.81\.4 - 首次发布：2026-10-15T01:39:46.045Z - 最新版本发布：2026-10-31T05:06:19.139Z - 近 30 天下载量：2093（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：14（近 12 个月 14 个） ## 中文简介 在您的 React Natural app 中显示一个 Colonal 的卡号, CVV, 过期和持卡人名, 而无需使用数据 . ## 安装 ```sh npm install @column-na/card-reveal-react-native ``` 也可以使用：`pnpm add @column-na/card-reveal-react-native`、`yarn add @column-na/card-reveal-react-native`、`bun add @column-na/card-reveal-react-native` ## README # @ co栏- na/ card- reveal- react- native 在您的 React Natural 或 Expo app 中显示一列卡的全号, CVV, 过期和持卡人名 。 卡片数据从不触及你的代码或服务器. 它纯粹是JavaScript,没有本土依赖性,因此在"博览会"(Expo Go),"博览会"(Expo)开发建设和"赤裸回放"(Bright React Industrial)中工作. 它需要回放19.1或更后,再回放"原住民"0.81或更后. ## 如何运作 1. **应用程序** 电话 `client.prepareReveal()`这使得揭示的一次性钥匙 并给应用它的拇指印, `keyThumbprint`。用卡片标识发送到您的服务器. 2. **您的服务器** 使用您的 API 密钥创建单一用途的显示符, 有效期为 1 分钟, 绑定在该密钥上 : ```sh curl -X POST 'https://api.column.com/issuing/cards//reveal-tokens' -u : \ -H 'Content-Type: application/json' -d '{"reveal_key_thumbprint": ""}' # {"id":"crtk_...","card_id":"card_...","expires_at":"...","reveal_key_thumbprint":"..."} ``` 请检查date=中的日期值 (帮助) 签入的用户先拥有卡. 那就只发信条 `id` 对应用程序. 3. **应用程序** 制作一个 `CardRevealText` 每个字段和呼叫 `prepared.reveal(...)`。请求直接从设备到Colonel的API,卡片细节会回到加密的结尾来结束一次性密钥,它会留在SDK的内存中. 值停留在SDK组件内:没有回调,回调或回调值会暴露出值. 信使只用那把钥匙,所以泄漏的信使对其他人都没用. ## 安装 ```sh npx expo install @column-na/card-reveal-react-native react-native-get-random-values # or: npm install @column-na/card-reveal-react-native react-native-get-random-values ``` 每一个揭示,活或沙盒,生成一个一次性的密钥,这需要安全的随机来源(S`crypto.getRandomValues`) (中文(简体) ). React Industrial的引擎不能提供一台,所以在您的应用程序的条目文件上方导入多填充器一次,先于其它任何设备: ```ts import 'react-native-get-random-values'; ``` 没有它, `reveal()` 掷出 `invalid_options`。 。 。 . 多填充是被披露者信任边界的一部分:一次性密钥只能像它给SDK的随机字节一样不可预测. 使用 `react-native-get-random-values`,用于安装 `crypto.getRandomValues` 由操作系统的安全随机源支持, 也在 Expo apps 中, 不要替换 `crypto.getRandomValues` 在显示真卡片的建筑里 装有Shim或测试杆 SDK在每个密钥之前检查源( 它拒绝全零输出或重复输出, 输出没有写入它传递的数组, 以及一个已变质的密钥) 并失败 `reveal_failed` 而不是发送一个可预测的密钥。 检查检查键的非常字节然后由来制成,所以一个多填法不能用一个字节来传递,而用另一个字节来种子这个键,但无法从一个攻击者可以复制的音源中分辨出. ## 使用量 ```tsx import { useEffect, useMemo, useRef } from 'react'; import { View } from 'react-native'; import { CardRevealError, CardRevealText, createCardRevealClient, type CardRevealTextHandle, } from '@column-na/card-reveal-react-native'; export function CardDetails({ cardId, createRevealToken, // asks your server for a token bound to the key: (keyThumbprint) => Promise }: { cardId: string; createRevealToken: (keyThumbprint: string) => Promise; }) { const client = useMemo(() => createCardRevealClient({ environment: 'live' }), []); // or 'sandbox' const pan = useRef(null); const cvv2 = useRef(null); const month = useRef(null); const year = useRef(null); useEffect(() => { let cancelled = false; let unmount = () => {}; (async () => { // One prepared key and one token per reveal: both are single use. const prepared = await client.prepareReveal(); const revealToken = await createRevealToken(prepared.keyThumbprint); if (cancelled) return; const reveal = prepared.reveal({ cardId, revealToken, fields: { pan, cvv2, expiration_month: month, expiration_year: year }, style: { color: '#fff', fontFamily: 'Menlo' }, fieldStyles: { pan: { fontSize: 20 } }, format: { pan: 'spaced', expirationYear: 'YY' }, }); unmount = reveal.unmount; await reveal.ready; })().catch((error) => { if (CardRevealError.is(error)) console.warn('Card reveal failed:', error.code); }); return () => { cancelled = true; unmount(); }; }, [client, cardId, createRevealToken]); return ( ); } ``` ### 反应绑定 `CardRevealProvider` 财务报告和审定财务报表 `CardRevealSlot` 在几行中也这样做: ```tsx import { CardRevealProvider, CardRevealSlot } from '@column-na/card-reveal-react-native'; myServer.createRevealToken(cardId, keyThumbprint)} > ; ``` - `mintToken({ cardId, keyThumbprint })` 请求您的服务器提供一个绑定在 启示的密钥上的符号并用它解决 `id`每一次都叫这个. - `` 是一个 `CardRevealText` 为那个领域取道具. - `` 还要 `style`, (中文(简体) ), `fieldStyles`, (中文(简体) ), `format`, (中文(简体) ), `timeoutMs` 财务报告和审定财务报表 `enabled` (默认) `true`· ; `false` 或隐藏显示的牌. - 在它内部, `useCardRevealState()` 返回时 `{ status, error, retry }`。 。 。 . `status` 实值 `'idle'`, (中文(简体) ), `'preparing'`, (中文(简体) ), `'minting'`, (中文(简体) ), `'revealing'`, (中文(简体) ), `'ready'` 或者说 `'error'`。 。 。 . `error` 是一个 `CardRevealError` 还是什么 `mintToken` 抛出. `retry()` 以新的键和符号开始 . - 改变客户端,卡片,插槽,样式, `format` 或者说 `timeoutMs` 以新符号再次显示; 卸载提供者 卸载显示并忘记任何未使用的密钥. - `useCardReveal({ client, cardId, mintToken, fields })` 跟钩子一样 `fields` 将每个字段映射到一个 `CardRevealText` 参考:. ### 按键符号 : `prepareReveal()` `client.prepareReveal()` 使下一个显示的一次性P-256键对在符号存在之前. 它决心: - `keyThumbprint`键的 [RFC 7638 (法语)](https://www.rfc-editor.org/rfc/rfc7638) SHA-256拇指印,基底64url不粘贴(43个字符). 传到你的服务器上 用它来铸造信物 `reveal_key_thumbprint`这是公用钥匙的散文 不是秘密. - `reveal(options)`:用该键显示,具有相同的选项和结果: `client.reveal()`。它可能被称为一次;第二次呼叫 `invalid_options`。在使用密钥前丢出无效的选项,所以更正后的调用仍然可以使用. - `discard()`:忘却了钥匙而不透露,因为当揭示不会发生时(信使不能被铸造出,或者屏幕移动了). 后来 `reveal()` 掷出 `invalid_options`。 。 。 . ```tsx const prepared = await client.prepareReveal(); const revealToken = await myServer.createRevealToken(cardId, prepared.keyThumbprint); const { ready, unmount } = prepared.reveal({ cardId, revealToken, fields: { pan, cvv2 } }); ``` 列只为发送密钥的启示回答绑定符. 任何其它密钥都有一个 `401` (单位:千美元)`reveal_failed`)),而代币并未用完. 私钥会留在SDK的记忆中,一旦披露的请求得到解决,或者披露被撕毁,就会被遗忘. `prepareReveal()` 拒绝方式 `invalid_options` (没有安全的随机来源,或生活在反应-内在-网络上)或 `reveal_failed`。 。 。 . 每一个显出的迹象都用一个 `reveal_key_thumbprint`,所以,每一次披露从 `prepareReveal()`。 。 。 . `client.reveal()` 选择相同的选项,但为另一个密钥刻出一个符号,或者没有准备的密钥的显示,得到一个 `401`。 。 。 . ### `CardRevealText` | Prop | 说明 | | --- | --- | | `placeholder` | 显示在披露之前和之后 `unmount`。 。 。 . | | `style` | 文本风格. 揭发 `style` 财务报告和审定财务报表 `fieldStyles` 在顶部应用. | | `selectable` | 用户是否可以选择(并复制)所显示的文本 。 默认 `false`。 。 。 . | | `testID` | 测试标识符. | ### 选项 | 选项 | 说明 | | --- | --- | | `cardId` | 该卡的身份证( E)`card_...`) (中文(简体) ). | | `revealToken` | 显式代号 ID (`crtk_...`从您的服务器上。 单用,有效期为一分. | | `fields` | 地图 `pan`, (中文(简体) ), `cvv2`, (中文(简体) ), `cardholder_name`, (中文(简体) ), `expiration_month`, (中文(简体) ), `expiration_year` 财务报告和审定财务报表 `pin` 改为 `CardRevealText` 参考: 每个字段使用不同的组件;见 [揭发PIN](https://npmcn.com/package/%40column-na/card-reveal-react-native/#readme-revealing-the-pin)。 。 。 . | | `style` 编号 : `fieldStyles` | 对每个字段或一个字段进行回放原生文字样式. | | `format.pan` | `'spaced'` (默认 : `4111 1111 1111 1111` 16位数字)或 `'plain'`。 。 。 . | | `format.expirationYear` | `'YYYY'` (违约)或 `'YY'`。 。 。 . | | `timeoutMs` | 多长时间 `ready` 在拒绝前等待 `timeout`. 默认为 15000,最高为 120000. | | `hidden` | `true` 显示被遮蔽的字段( e)`••••`直到你打电话 `show()`默认 `false`。 。 。 . | | `autoHideMs` | 卸载此数毫秒之后的显示 `ready` 决议(1至360000). | | `onAutoHide` | 打电话一次 `autoHideMs` 卸载显示. | ### `ready`, (中文(简体) ), `unmount`, (中文(简体) ), `hide` 财务报告和审定财务报表 `show` - `ready` 一旦每个字段都显示其价值,就解决. - 如果有球场失败,或者超时, `ready` 拒绝,每一个字段都回到它的占位符. - `unmount()` 做同样的。 若为 `ready` 仍然悬而未决,它拒绝 `unmounted`。 。 。 . - `hide()` 财务报告和审定财务报表 `show()` 面罩并解开每个字段;见 [隐藏、显示和复制](https://npmcn.com/package/%40column-na/card-reveal-react-native/#readme-hide-show-and-copy)。 。 。 . - 丢弃无效的选项 `invalid_options` 同步进行. ### 隐藏、显示和复制 - `reveal.hide()` 口罩每个字段(每个字符但空格显示为 `•`和 `reveal.show()` 重新显示它,没有新的符号或请求。 一个蒙面 `CardRevealText` 无法选择。 两人之后什么都不做 `unmount()` 或者失败. `hidden: true` 开始伪装. - `autoHideMs` 删除长时间后的值 `ready`,作为 `unmount()` 誓以报应 `onAutoHide` 一次 一次吗 再次显示它们需要一个新的标志. - **复制 :** React Industrial 没有本地模块的剪贴板 API ()`@react-native-clipboard/clipboard` 或者说 `expo-clipboard`)),而这个SDK没有本土代码,因此它没有提供复制按钮. `copyable` 财务报告和审定财务报表 `onCopy` 仅是网并投掷 `invalid_options` 在这里。 设定 `selectable` 打开 `CardRevealText` 这样持卡人就可以与系统文本选择一起复制. ### 错误 每个错误都是 `CardRevealError` 拥有稳定 `code`数字 : `invalid_options`, (中文(简体) ), `container_not_found` (一名裁判不是挂在挂上) `CardRevealText`, (中文(简体) ), `reveal_failed`, (中文(简体) ), `timeout` 财务报告和审定财务报表 `unmounted`。 。 。 . `field` 和 HTTP 软件 `status` 当人们知道的时候 `apiCode` 当列的 API 返回出错代码时。 A 类 `401` 指代号缺失,无效,已经使用,过期,用于不同的卡片或绑入不同的显示密钥. 信件中从不包含令牌或卡数据,SDK也从不登录. ### 揭发PIN 添加 `pin` 改为 `fields` 显示借记卡的PIN。 SDK 只为您列出的字段询问列, 所以 PIN 只在您包含时返回 `pin`,而只有PIN的显示不能返回卡号或CVV. 您的服务器以同样的方式创建出信号符 。 该卡的程序必须允许 PIN 显示 。 在你透露他们的PIN前 检查持卡人. 启示 `pin` 而不是卡片号码旁边 如果PIN不能被揭示,整个揭示失败了,所以与其他域一起要求它也会隐藏这些. 当它失败时, `reveal_failed` 将列的错误代码载入 `apiCode`数字 : | `apiCode` | 含义 | | --- | --- | | `pin_not_revealable` | PIN是在PIN披露之前设定的. 重新设置 PIN 使其可公开 . | | `feature_not_enabled` | PIN显示卡程序没有启用. | | `invalid_field_value` | 该卡没有PIN,或者不是借记卡. | 这些失败发生在使用显式符号之前, 所以同样的显式仍然有效 `pin`。 。 。 . ## 沙盒活下来 | | 现场直播 | 沙盒 | | --- | --- | --- | | 数据 | 真实牌 | 模拟牌 | | 请求 | 直接列 : `GET https://api.column.com/issuing/cards/{id}/reveal` 与 `Live-Mode: Yes`,加密端为结束 | 同一请求与 `Live-Mode: No`,同时加密 | 都变成这样 `CardRevealText` 组件。 在沙盒里, `sandboxBaseUrl` 可以指向本地的模拟。 使用 `http://127.0.0.1:` iOS 模拟器和 `http://10.0.2.2:` 在Android模拟器上. 现场直播在React Industrial Web上无法提供,它扔到那里 `invalid_options`。在网络上,使用 [`@column-na/card-reveal`](https://www.npmjs.com/package/@column-na/card-reveal),将卡片数据保存在孤立的 iframes 中. ## 版本 这个软件包遵循语义化的版本,并以与Web SDK相同的版本发布. 每个请求都会发出 `X-Column-SDK-Version: card-reveal-react-native/`。 。 。 . SDK没有发出分析. ## 许可证 专有. 使用须遵守列卡显示的 SDK 许可证 `LICENSE` 并需要与Colle协议. ## 常见问题 ### @column-na/card-reveal-react-native 是什么？ 在您的 React Natural app 中显示一个 Colonal 的卡号, CVV, 过期和持卡人名, 而无需使用数据 \. ### 如何安装 @column-na/card-reveal-react-native？ 在项目目录运行 npm install @column-na/card-reveal-react-native，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.1\.0）、react-native（\>=0\.81\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @column-na/card-reveal-react-native 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @column-na/card-reveal-react-native 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @column-na/card-reveal-react-native 可以商用吗？ @column-na/card-reveal-react-native 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。 ### @column-na/card-reveal-react-native 的下载量有多少？ 根据 npm 官方下载统计，@column-na/card-reveal-react-native 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,093 次，日均约 70 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @column-na/card-reveal-react-native 还在维护吗？ 最新版本 0\.13\.0 发布于 2026/10/31（10 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。