Go go-vcard 的结构化姓名与显示姓名有什么区别

用 Go 处理 vCard 时，最容易混淆的是 N 和 FN：前者是可拆分的结构化姓名，后者是给人直接看的格式化姓名。go-vcard 用 vcard.Name 表示 N 的 FamilyName、GivenName 等组件，用 FieldFormattedName（值为 FN）保存显示文本。导入联系人时需要先看清这两个字段的职责，否则排序、拼接和界面展示很容易互相污染。

官方文档：https://pkg.go.dev/github.com/emersion/go-vcard

一句话判断：要拆分、排序或生成新的联系人格式，读取 N；要在列表中直接显示，读取 FN。两者可以不同，但不应把一个字段当成另一个字段的替代品。

不要用 FN 反推结构化姓名

在 vCard 规范里，N 是姓名组件集合，FN 是完整显示名。比如一张名片可以写成 N:Doe;Jane;Q.;Dr.;Jr.，同时写成 FN:Dr. Jane Q. Doe Jr.。显示名的标点、顺序和称谓不是稳定的拆分协议，拿它再按空格切分，会在中文姓名、复姓或包含后缀时产生错误。

读取首选姓名与全部姓名

Card.Name() 返回首选的结构化姓名，没有该字段时返回 nil；Card.Names() 则保留所有 N 字段。显示名对应的 FormattedNames() 也可能有多个值。只有在你明确只关心一个字段时，才使用 PreferredValue，并给空字符串准备降级策略。

package main

import (
    "fmt"
    vcard "github.com/emersion/go-vcard"
)

func printName(card vcard.Card) {
    // N 用于结构化处理：不要从 FN 再次按空格猜测姓和名。
    if name := card.Name(); name != nil {
        fmt.Printf("结构化：姓=%q 名=%q 中间名=%q\n", name.FamilyName, name.GivenName, name.AdditionalName)
    }

    // FN 用于直接展示；PreferredValue 只取首选字段的文本值。
    display := card.PreferredValue(vcard.FieldFormattedName)
    if display == "" {
        display = "未命名联系人"
    }
    fmt.Println("显示：", display)
}

这里的“首选”不是把 N 和 FN 合并，而是在同一个属性存在多个字段时按参数选择一个。若业务需要保留别名、法定姓名和显示昵称，应遍历 Names() 或 FormattedNames()，不要只保存一个字符串。

写入时让 N 和 FN 各司其职

生成联系人时，建议把组件填进 vcard.Name，把最终面向用户的文本单独放进 FN。SetName 会替换已有的结构化姓名，SetValue 会替换指定属性的单个值；如果需要并存多个字段，改用 AddName 或 AddValue。编码前还要有 VERSION，因为 Encoder.Encode 要求卡片包含版本字段。

card := make(vcard.Card)

// 用组件表达可排序的姓名，空的 AdditionalName 不需要人为填占位符。
card.SetName(&vcard.Name{
    FamilyName: "Doe",
    GivenName: "Jane",
    AdditionalName: "Q.",
    HonorificPrefix: "Dr.",
    HonorificSuffix: "Jr.",
})

// FN 是展示层文本，可以按产品界面需要调整顺序和称谓。
card.SetValue(vcard.FieldFormattedName, "Dr. Jane Q. Doe Jr.")
// Encoder.Encode 需要版本字段；这里示例使用 vCard 4.0。
card.SetValue(vcard.FieldVersion, "4.0")

如果输入来源只给了 FN，可以把它作为显示名保存，但不要假装已经得到可靠的 FamilyName 和 GivenName。反过来，如果只有 N，可以按产品规则拼一个 FN，但要把它视为生成的展示值，不能覆盖原始组件。

多值、空值与版本转换的检查清单

实际导入流程建议按下面顺序判断：先检查 Card.Name() 是否为空，再决定是否遍历 Names()；显示层优先取 PreferredValue(FieldFormattedName)，为空时才用业务允许的降级文本。需要把旧卡片转为 vCard 4 时可以调用 vcard.ToV4(card)，但它是版本转换，不会替你修复缺失或错误的姓名组件。

• 只展示：优先 FN，避免界面出现意外的字段顺序。
• 排序或导出：优先 N 的 FamilyName、GivenName，空组件要允许存在。
• 保留别名：读取全部 N/FN，而不是把多值压成一个 map 项。
• 兼容旧数据：保留原始字段，转换版本后再编码，方便追查来源。

常见问题

FN 为空时能否直接显示 N？

可以把 N 的组件按产品规则拼接成临时显示名，但应明确这是降级结果，并处理空组件；不要把它写回 FN 覆盖原始数据。

Card.Name 和 Card.Names 应该选哪个？

只需要首选姓名时用 Name；要保留别名、历史姓名或多个 N 字段时用 Names。它们分别对应“首选对象”和“完整集合”。

SetName 后还要手动写 N 的 Value 吗？

通常不需要。用 Name 的组件表达结构化姓名，再用 SetValue 写 FN 和 VERSION；只有需要保留特殊参数或原始字段时，才直接操作 Field。