NFC 标签

asuka/sdk/nfc 用来读写 NFC 标签：标签上的 NDEF 消息（链接、文本、应用自己的数据）、标签本身（ID 和技术类型），以及发给标签的原始命令。它做的事和 react-native-nfc-manager、Web NFC 一样，只是在每个平台上都用平台自己的 API：iOS 上是带系统面板的 Core NFC，Android 上是读卡器模式（reader mode），Web 上是 Chrome for Android 的 Web NFC。Mac、PC 和 Linux 会如实回答它们没有 NFC。

s := nfc.Start(nfc.Options{Alert: "Hold your iPhone near the tag."}, func(t *nfc.Tag) {
	if u, ok := t.Message.URI(); ok {
		link.Set(u)
	}
	s.Stop()
})

examples/nfc 读取标签上的链接，也能把链接写进标签。

有没有 NFC，开没开

nfc.Check 告诉你设备有没有 NFC（Supported）以及它是否打开（Enabled），不能在主线程上调用。nfc.Use 把同样的信息作为 signal 提供给组件，在组件存活期间跟随 Android 上的开关变化；nfc.Watch 则在每次变化时调用一个函数。

state := nfc.Use()
ui.Show(signal.Func(func() bool { s := state.Get(); return s.Supported && !s.Enabled }), func() ui.Node {
	return ui.Button(ui.ButtonProps{Title: ui.Val("Turn NFC On"), OnPress: func() { go nfc.OpenSettings() }})
})

iPhone 从 iPhone 7 起就有 NFC，而且没有开关，所以在 iPhone 上 Enabled 和 Supported 相同。iPad 和 iOS 模拟器没有 NFC。在 Android 上，OpenSettings 会打开系统的 NFC 设置，让用户把它打开；在其他平台上它返回 ErrNotAvailable。浏览器在会话发现 NFC 关着（ErrDisabled）之前，没法知道它是否关闭。

读取标签：会话

nfc.Start 开始一个寻找标签的会话，每找到一个标签，就在主线程上调用它的函数。如果在组件里调用（组件函数体或 effect 中），会话会随组件的 owner 一起结束；如果在事件处理函数里调用，会话会一直持续，直到 Stop、Fail，或者（在 iOS 上）用户关掉面板或者超时。同一时间只有一个会话：开始新会话会结束之前的那个。

会话结束时会调用 Options.OnEnd：如果是应用自己结束的，参数为 nil；用户关掉 iOS 的面板时为 nfc.ErrCanceled；iOS 的六十秒到期后为 nfc.ErrTimeout；会话没能开始时则是 ErrNotAvailable、ErrDisabled 或 ErrDenied。

Tag 记录了标签被发现时提供的信息：它的 ID、Techs、NDEF 状态（NDEF：Format、Capacity、CanMakeReadOnly，以及 Android 的 Type）和它的 Message（没有读取时为 nil）；平台提供的话，还有对应技术的细节（ISO7816、FeliCa、ISO15693、MIFARE、NfcA、NfcB、Barcode、MaxTransceive）。

一次一个标签

会话一次只把一个标签交给应用，并在应用处理它期间一直持有它：再次读取、写入、发送命令都可以。处理完后，Next 放开这个标签，继续寻找下一个。应用持有一个标签时靠近的其他标签，会等到 Next 之后再交给应用。在 iOS 上，Next 会重新开始轮询，所以仍然靠着手机的标签会被再次发现；Android 只在标签靠近的那一刻才会发现它。

nfc.Start(nfc.Options{OnEnd: ended}, func(t *nfc.Tag) {
	count.Update(func(n int) int { return n + 1 })
	s.Next() // 下一个标签
})

iOS 的系统面板

在 iOS 上，会话会显示系统的面板。Options.Alert 是寻找标签时面板上显示的文字，SetAlert 可以修改它（比如 "Writing…"）。Stop 会让面板带着对勾和当前提示文字关闭；Fail("Couldn't write the tag.") 则让面板显示这条失败信息后关闭。Android 和 Web 不显示面板：应用自己展示界面，提示文字在那里不起作用。

Options.Poll 决定使用哪种会话。不设置时，iOS 使用 NFCNDEFReaderSession 读取带 NDEF 消息的标签：这样找到的标签没有 ID，也不能接收原始命令。设置之后（nfc.PollA、PollB、PollF、PollV、PollPACE 或 PollAll），iOS 改用 NFCTagReaderSession 轮询这些类型的标签，可以拿到 ID，也能发送命令。ISO 7816 卡需要在 asuka.json 的 nfc.iso7816 里列出它的应用，FeliCa 卡需要在 nfc.felica 里列出系统代码：iOS 不会发现其他的卡。

Android 的读卡器模式

在 Android 上，会话就是为前台页面开启的读卡器模式（enableReaderMode）：标签会交给这个应用而不是其他应用，Android 也不会显示自己的标签界面。当某个 Activity 回到前台时，会为它重新开启。Options.Poll 对应读卡器模式的标志（不设置则是所有类型）；SkipNDEF 让系统在发现标签时不读取 NDEF 消息（FLAG_READER_SKIP_NDEF_CHECK，对只接收命令的标签更快）；NoSound 关掉平台的提示音，方便应用使用自己的反馈（ui.Haptic）；PresenceDelay 是 Android 检查标签是否还在的时间间隔。

NDEF 消息和记录

NDEF 消息就是 nfc.Message：由多条 Record 组成，每条记录都有 TNF、Type、ID 和 Payload。下面这些函数用来创建应用最常用的记录：

Message.URI 是第一条记录的 URI（URI 记录、绝对 URI，或者智能海报中的链接），也就是 Android 打开应用时使用的那个；Message.Text 是第一条文本。Message.Encode 和 nfc.Decode 负责消息与标签上实际字节之间的转换（Decode 会把分块的记录拼接起来）；空标签上的消息是一条空记录，解码后是一个空的 Message。

写入标签和设为只读

应用持有标签时，Write 用新消息替换标签上的消息，MakeReadOnly 则永久锁定标签：之后谁也不能再写它。这两个调用都要等待标签响应，所以要在 goroutine 里调用，再回到主线程处理会话。

nfc.Start(nfc.Options{Alert: "Hold your iPhone near a tag to write it."}, func(t *nfc.Tag) {
	if !t.NDEF.Writable() {
		s.Fail("This tag can't be written.")
		return
	}
	s.SetAlert("Writing…")
	go func() {
		err := t.Write(nfc.Message{nfc.URI("https://example.com/t/42")})
		ui.Post(func() {
			if err != nil {
				s.Fail("Couldn't write the tag.")
				return
			}
			s.Stop()
		})
	}()
})

对已锁定的标签，Write 返回 ErrReadOnly；消息超过 NDEF.Capacity 时返回 ErrTooLarge；Formatable 的标签（还不是 NDEF 格式，即 Android 的 NdefFormatable）会在写入时被格式化。Read 重新读取消息，Status 重新查询 NDEF 状态。标签离开或被放开之后，这些调用会返回 ErrTagLost。

标签本身：ID、技术类型和命令

Tag.Techs 是标签具备的技术类型。两个平台都会报告 nfc.NDEF、ISO7816（ISO 7816 卡，即 ISO 14443-4）、MIFARE（ISO 14443-3A 标签：NTAG、MIFARE Ultralight、DESFire）、FeliCa 和 ISO15693；Android 还会报告自己的类型（NfcA、NfcB、NfcF、NfcV、IsoDep、MifareClassic、MifareUltralight、NDEFFormatable、NfcBarcode）。ID 是平台给出的标签标识符（Android 上 NFC-V 的 ID 是低字节在前）。

Transceive 发送原始命令并返回响应。iOS 需要设置了 Poll 的会话；Web 不支持（ErrNotSupported）。

r, err := t.Command(nfc.SelectAID(aid)) // 按 AID 执行 SELECT
if err == nil && r.OK() {
	r, err = t.Command(nfc.APDU{CLA: 0x00, INS: 0xB0, P1: 0, P2: 0, Le: 256}) // READ BINARY
}

nfc.APDU 会根据数据和 Le 的需要，把命令编码成短格式或扩展格式；Response 包含 Data、SW1 和 SW2（OK 表示 90 00）。

MIFARE Classic 的扇区只能在 Android 上读写（iOS 不支持 MIFARE Classic）：先用扇区的密钥 A 或 B 调用 ClassicAuth，然后用 ClassicRead 和 ClassicWrite 读写 16 字节的块；值块则用 ClassicValue（Increment、Decrement、Restore、Transfer）。

能打开应用的标签

应用没有打开时，标签也能打开它，或者把它带到前台：

• iOS 会在后台读取标签（iPhone XS 及更新的机型），当标签的第一条记录是某个应用的通用链接时，提示用户打开该应用：也就是 asuka.json 的 links 中、域名提供了 apple-app-site-association 文件的链接。这个链接会像其他链接一样交给 ui.OnOpenURL。
• Android 会为 asuka.json 中 nfc.ndef（NDEF_DISCOVERED，按消息的第一条记录匹配：URI、MIME 类型或外部类型）和 nfc.tech（TECH_DISCOVERED，按技术类型匹配）列出的标签打开应用。带 URI 的标签交给 ui.OnOpenURL；其他标签作为 Tag 交给 nfc.OnOpen，标签还在附近时，应用依然可以读写它、给它发命令。属于应用 links 的 https 标签还会作为 App Link 打开应用。

ui.OnOpenURL(func(u string) { link.Set(u) })
nfc.OnOpen(func(t *nfc.Tag) {
	if mt, ok := t.Message[0].MediaType(); ok && mt == "application/vnd.example.ticket" {
		ticket.Set(string(t.Message[0].Payload))
	}
})

在设置处理函数之前到达的标签（比如启动应用的那个标签）会一直等到第一个处理函数出现。nfc.OnOpen 会随组件的 owner 一起停止，也可以调用它返回的函数停止。会话运行期间到达的标签交给会话，而不是这里。

asuka.json 与权限

导入了 asuka/sdk/nfc 的应用会获得 Android 的 NFC 权限和 uses-feature android.hardware.nfc（非必需：没有 NFC 的手机也能安装），以及 iOS 上的 NFCReaderUsageDescription（在 ios.usage 里写你自己的说明）和 Core NFC 的 entitlement com.apple.developer.nfc.readersession.formats（NDEF 和 TAG）。发布构建的 App ID 需要开启 NFC Tag Reading 能力：如果描述文件缺少它，asuka build 会提示你。

asuka.json 的 nfc 用来补充应用的标签所需的配置：

"nfc": {
  "iso7816": ["D2760000850101"],
  "felica": ["8008"],
  "ndef": [{ "uri": "https://example.com/t/" }, { "mime": "application/vnd.example.ticket" }, { "external": "example.com:ticket" }],
  "tech": [["IsoDep"], ["NfcA", "MifareUltralight"]],
  "required": true
}

这些配置只会加到导入了这个包的应用里。见 asuka.json。

在 asuka dev 中

iOS 模拟器和 Android 模拟器都没有 NFC：Check 会报告不支持。在 Android 手机上，开发 App 带有 NFC 权限，所以在 asuka dev 的热重载模式下，会话、读取、写入和命令都能用；能打开应用的标签则不行（过滤器只存在于应用自己的构建里：请用 --no-hot 测试，asuka dev 也会提示）。在 iPhone 上，开发 App 的描述文件需要开启 NFC Tag Reading 能力；ISO 7816 卡和 FeliCa 则需要应用自己的构建（它们的 AID 和系统代码写在应用的 Info.plist 里），所以配置了 nfc.iso7816 或 nfc.felica 的应用，asuka dev 会构建成应用本身来运行，而不使用热重载模式。Web NFC 需要安全上下文，而 --lan 的地址不是：运行 asuka dev --platform web，把端口转发到手机（adb reverse tcp:<port> tcp:<port>），再在手机的 Chrome 里打开 http://localhost:<port>。

各平台上的表现

桌面端的 USB NFC 读卡器是智能卡读卡器（PC/SC）：它们能读卡片的 APDU，但没法以一种通用于各种读卡器的方式读取标签上的 NDEF 消息（每家厂商的命令都不一样），也没有可以配合会话面板的刷卡流程。所以 Asuka 没有支持它们；需要的话，可以通过原生包访问（winscard.dll、pcsc-lite、CryptoTokenKit）。

用模拟标签测试

host/fake 的 NFC 为应用的界面测试（见测试）模拟手机的 NFC：Tap 把标签靠近正在运行的会话，Cancel 和 Timeout 像 iOS 那样结束会话，Remove 把标签拿开，Open 用一个标签打开应用，SetEnabled 可以关闭 NFC。fake.NFCTag 保存着它的 NDEF 消息字节，应用写入后这些字节会随之改变。

func TestRead(t *testing.T) {
	var n *fake.NFC
	a := uitest.Mount(t, Tags, uitest.Setup(func(h *fake.Host) { n = h.NFC() }))
	a.Tap("Read a Tag")
	a.Until("a session", func() bool { return n.Session != nil })
	n.Tap(&fake.NFCTag{NDEF: nfc.Message{nfc.URI("https://example.com/hello")}.Encode()})
	a.WaitFor("https://example.com/hello")
}

n.Session 是正在运行的会话，包括它的 Alert、Poll 和其他选项；标签的 Transceive 和 Classic 负责回答发给它的命令。