能力中的 API
Web NFC API
发布于 更新于
NDEFReader 让 Web 应用读写贴近手机的 NFC 标签,消息格式为 NFC Data Exchange Format(NDEF)。scan() 开始监听,每当标签进入范围就触发带标签序列号和记录的 reading 事件;write() 把一条消息写入下一个靠近的标签;makeReadOnly() 把标签永久锁定。PWA 可以用它做库存标签、活动签到,或与贴有 NFC 贴纸的设备配对;NDEF 之外的底层标签协议不对外暴露。
Android 版 Chrome 89 是唯一的实现:它提供 NDEFReader、scan()、write() 以及 reading 与 readingerror 事件,Android 版 Chrome 100 加入 makeReadOnly()(BCD api.NDEFReader)。跟随 Chrome 的 Android Chromium 浏览器(如 Samsung Internet)继承该支持;桌面 Chrome、Firefox 与 Safari 均无支持,WebKit 已提交「反对」立场(standards-positions #584)。
const reader = new NDEFReader()
reader.scan()reader.scan(options)reader.write(message)reader.write(message, options)reader.makeReadOnly()reader.makeReadOnly(options)三个方法都返回 Promise<undefined>。scan() 开始监听就兑现,此时还没有读到标签。读取结果由 reading 事件送达,事件类型为 NDEFReadingEvent,带有 serialNumber 和 message;标签在范围内但读取失败时,触发 readingerror。
write() 和 makeReadOnly() 要等写入或锁定完成才兑现,标签尚未靠近时可能要等数秒。接口声明为 [SecureContext, Exposed=Window],仅限顶层浏览上下文,页面不可见时暂停。
scan() 与 makeReadOnly() 各接受一个可选字典;write() 接受一条消息和一个可选字典。
| 方法 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
scan() |
options |
NDEFScanOptions { signal } |
否 | signal(AbortSignal)停止监听,并把该 reader 从活动集合中移除。 |
write() |
message |
NDEFMessageSource:DOMString、BufferSource 或 NDEFMessageInit |
是 | 字符串变成一条 "text" 记录,缓冲区变成一条类型为 application/octet-stream 的 "mime" 记录,NDEFMessageInit 则显式给出记录。 |
write() |
options |
NDEFWriteOptions { overwrite = true, signal } |
否 | overwrite: false 时,标签上已有 NDEF 记录则拒绝写入。signal 中止挂起的写入。 |
makeReadOnly() |
options |
NDEFMakeReadOnlyOptions { signal } |
否 | signal 中止挂起的锁定。 |
NDEFMessageInit 只有一个必填成员 records,类型为 sequence<NDEFRecordInit>。
NDEFRecordInit 成员 |
类型 | 必填 | 说明 |
|---|---|---|---|
recordType |
USVString |
是 | "empty"、"text"、"url"、"smart-poster"、"mime"、"absolute-url"、"unknown",形如 "example.com:shelf" 的外部类型,或智能海报内部形如 ":act" 的本地类型。 |
mediaType |
USVString |
否 | 载荷的 MIME 类型,只有 "mime" 记录使用,缺省或无法解析时按 application/octet-stream 处理;其他记录类型都不得携带。 |
id |
USVString |
否 | 记录标识符;"empty" 记录不得携带。 |
encoding |
USVString |
否 | 仅用于 "text":"utf-8"(默认)、"utf-16"、"utf-16be" 或 "utf-16le"。UTF-16 系列要求 data 是 BufferSource;data 为 DOMString 时只接受 "utf-8" 或省略。 |
lang |
USVString |
否 | "text" 记录的 BCP 47 语言标签,如 "zh";默认取文档语言。 |
data |
any |
视类型而定 | "text" 用 DOMString 或 BufferSource;"url"、"absolute-url" 用 DOMString;"mime"、"unknown" 用 BufferSource;外部类型与本地类型用 BufferSource 或 NDEFMessageInit;"smart-poster" 只能用 NDEFMessageInit;"empty" 省略。 |
NDEFMessageInit 的嵌套最多 32 层,外部类型名不得超过 255 字节。
在返回 Promise 之前执行的检查会立即拒绝;其余检查发生在用户授予 nfc 权限之后。
| 异常 | 方法 | 条件 |
|---|---|---|
InvalidStateError |
全部 | 调用方不是活动的顶层浏览上下文(iframe 被拒),或对 scan() 而言该 reader 已在扫描中。 |
信号的 abort reason(默认 AbortError) |
全部 | 调用时 options.signal 已中止,或操作挂起期间被中止。 |
TypeError |
write() |
消息无效:records 为空;嵌套超过 32 层;禁止携带 mediaType 或 id 的记录类型带了它们;data 类型与 recordType 不匹配;"text" 的 encoding 不在允许的四种之内,或 DOMString 数据配了 UTF-16 编码;外部类型名超过 255 字节;或 "smart-poster" 没有恰好一条 URL 记录。 |
SyntaxError |
write() |
"url" 或 "absolute-url" 记录的 data 无法解析为 URL,或 "text" 的 lang 超过 63 字节。 |
NotAllowedError |
全部 | 用户拒绝了 nfc 权限,或(overwrite: false 的 write())标签上已有 NDEF 记录。 |
NotSupportedError |
全部 | 设备没有 NFC 适配器或无法连接适配器。write() 另外在适配器不支持推送数据,或标签不暴露 NDEF 技术且无法格式化时触发。扫描时遇到不兼容的标签会触发 readingerror,不会拒绝 scan()。 |
NotReadableError |
全部 | 浏览器不被允许使用适配器,例如系统设置中已关闭 NFC。 |
NetworkError |
write()、makeReadOnly() |
向标签传输或锁定操作失败,例如标签在写入途中被移开。 |
scan() 本身不会报告无法读取的标签:那会以不带载荷的 readingerror 事件到达 reader,处理函数应提示用户稳住标签再试一次。
使用前先检测 window 中是否有 NDEFReader。桌面浏览器和 iOS 会走回退分支,可以让用户扫描二维码或手动输入同一标识符。
扫描标签,缺少支持时回退到二维码
链接到“扫描标签,缺少支持时回退到二维码”一节从一次点击开始扫描,让权限提示与手势绑定;解码 "text" 与 "url" 记录,没有 Web NFC 时显示二维码扫描器。scan() 在监听开始时兑现,真正的读取稍后通过 reading 事件到达。
async function startTagScan(onTag, showQrFallback) { if (!('NDEFReader' in window)) { showQrFallback(); return; }
const reader = new NDEFReader(); reader.addEventListener('reading', ({ serialNumber, message }) => { const decoder = new TextDecoder(); for (const record of message.records) { if (record.recordType === 'text') onTag({ serialNumber, text: decoder.decode(record.data) }); if (record.recordType === 'url') onTag({ serialNumber, url: decoder.decode(record.data) }); } }); reader.addEventListener('readingerror', () => onTag({ error: '标签无法读取,请稳住标签再试一次。' }));
try { await reader.scan(); } catch (err) { if (err.name === 'NotAllowedError') showQrFallback(); else throw err; }}record.data 是 DataView。"text" 记录的编码和语言分别保存在 record.encoding 和 record.lang 中。读取 UTF-16 标签时,用 new TextDecoder(record.encoding) 指定编码,不能用默认值。
只向空白标签写入 URL,并设置超时
链接到“只向空白标签写入 URL,并设置超时”一节overwrite: false 保护已有数据的标签,AbortSignal 在十秒内没有标签靠近时停止挂起的写入。没有 Web NFC 时函数返回 false,界面可以改为提供打印二维码标签的选项。
async function writeLabel(url) { if (!('NDEFReader' in window)) return false;
const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 10_000); try { await new NDEFReader().write( { records: [{ recordType: 'url', data: url }] }, { overwrite: false, signal: controller.signal }, ); return true; } catch (err) { if (err.name === 'AbortError') return false; // 10 秒内没有标签 if (err.name === 'NotAllowedError') throw new Error('标签已有内容,或 NFC 权限被拒绝'); throw err; } finally { clearTimeout(timer); }}标签在传输途中移开会以 NetworkError 拒绝。规范没有说明标签上留下了什么,信任它之前先读回来看;如果第一次尝试已经留下记录,用 overwrite: false 重试会被拒绝。
写入厂商记录并锁定标签
链接到“写入厂商记录并锁定标签”一节外部记录类型让应用在自己的命名空间下存放结构化数据。写入后 makeReadOnly() 锁定标签,访客的手机就无法改动它;锁定不可逆,所以示例先请求确认。
async function provisionShelfTag(shelfId, confirmLock) { if (!('NDEFReader' in window)) return 'unsupported';
const reader = new NDEFReader(); const payload = new TextEncoder().encode(JSON.stringify({ shelfId })); await reader.write({ records: [{ recordType: 'example.com:shelf', data: payload }] });
if (!(await confirmLock())) return 'written'; try { await reader.makeReadOnly(); return 'locked'; } catch (err) { if (err.name === 'NotSupportedError') return 'written-not-lockable'; throw err; }}外部类型 example.com:shelf 必须使用你控制的域名,域名转成 ASCII 后整个类型名不超过 255 字节;读回时 recordType === 'example.com:shelf',record.data 中是同样的字节。
另请参阅
链接到“另请参阅”一节- Web Bluetooth API,用于附近的低功耗蓝牙设备,这是 NFC 标签扫描之外的另一种传输
- WebHID API
- WebUSB API
- Web NFC: NDEFReader scan() method(w3c-cg.github.io)
- Web NFC: security policies(w3c-cg.github.io)
- WebKit standards position: Web NFC(github.com)
- Interact with NFC devices on Chrome for Android(developer.chrome.com)
规范
| 规范 | 状态 |
|---|---|
| Web NFC API | 社区草案 |
| Web NFC: NDEFReader scan() method | 社区草案 |
| Web NFC: NDEFReader write() method | 社区草案 |
| Web NFC: NDEFReader makeReadOnly() method | 社区草案 |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| Chrome (Desktop)# | 不支持 | — | 高 | 来源 | 1 |
| Chrome (Android)# | 支持 | 89 | 高 | 来源 | — |
| Edge (Desktop)# | 不支持 | — | 高 | 来源 | 23 |
| Firefox (Desktop)# | 不支持 | — | 高 | 来源 | 4 |
| Firefox (Android)# | 不支持 | — | 高 | 来源 | 56 |
| Safari (macOS)# | 不支持 | — | 高 | 来源 | 7 |
| Safari (iOS)# | 不支持 | — | 高 | 来源 | 89 |
| Samsung Internet# | 支持 | 15.0 | 高 | 来源 | 10 |
| WebView (Android)# | 支持 | 89 | 高 | 来源 | 11 |
- browser-compat-data 未记录 Chrome 的支持。
- browser-compat-data 未记录 Edge 的支持。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- browser-compat-data 未记录 Firefox 的支持。
- browser-compat-data 未记录 Firefox for Android 的支持。
- 由 browser-compat-data 镜像自 Firefox 的数据推导。
- browser-compat-data 未记录 Safari 的支持。
- browser-compat-data 未记录 iOS 版 Safari 的支持。
- 由 browser-compat-data 镜像自 Safari 的数据推导。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。