跳转到内容

能力中的 API

Web NFC API

发布于 更新于

有限可用不支持的浏览器: Chrome (Desktop)、Edge (Desktop)、Firefox (Desktop)、Firefox (Android)、Safari (macOS)、Safari (iOS)社区草案

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 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
  1. browser-compat-data 未记录 Chrome 的支持。
  2. browser-compat-data 未记录 Edge 的支持。
  3. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  4. browser-compat-data 未记录 Firefox 的支持。
  5. browser-compat-data 未记录 Firefox for Android 的支持。
  6. 由 browser-compat-data 镜像自 Firefox 的数据推导。
  7. browser-compat-data 未记录 Safari 的支持。
  8. browser-compat-data 未记录 iOS 版 Safari 的支持。
  9. 由 browser-compat-data 镜像自 Safari 的数据推导。
  10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  11. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/web-nfc.json · 全球使用占比: 36 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-03 · 置信度: 高 (由来源计算)