Go go-ical 文本中的逗号和换行应该怎样转义

用 github.com/emersion/go-ical 生成日历时，SUMMARY 或 DESCRIPTION 里出现逗号、分号、反斜杠和换行，不能直接把字符串拼到 NAME:VALUE 后面。它们在 iCalendar 的 TEXT 值里有自己的转义含义：逗号可能是多值分隔符，反斜杠是转义起点，换行要写成 \\n。最稳妥的做法是把业务字符串交给 SetText 或 SetTextList。

官方地址：https://pkg.go.dev/github.com/emersion/go-ical

先把业务文本和 iCalendar 保留字符分开

go-ical 的 Prop 将 TEXT 值保存在属性内容中。按照它的实现，写入时反斜杠、分号和逗号会先加反斜杠，业务换行会变成两个字符 \\n。读取时再逆向还原：\\\\、\\;、\\, 分别回到原字符，\\n 或 \\N 回到换行。

因此，下面这组对应关系是文章的核心。表中的“线格式”指属性值在 iCalendar 文本中的写法，不是 Go 源码字符串字面量本身。

写入时优先使用 SetText，列表才使用 SetTextList

SetText 内部会把一个字符串作为只有一个元素的 TEXT 列表处理，所以适合标题、地点、描述等单值属性。只有当属性语义确实是多个 TEXT 值时，才把多个元素传给 SetTextList。不要为了“看起来像列表”而手动用逗号拼接字符串。

package main

import (
	"bytes"
	"fmt"
	"log"

	ical "github.com/emersion/go-ical"
)

func buildCalendar() (string, error) {
	// 单个 SUMMARY 中的逗号和换行属于业务文本，交给 SetText 自动转义。
	event := ical.NewEvent()
	event.Props.SetText(ical.PropUID, "meeting-001@example.org")
	event.Props.SetText(ical.PropSummary, "会议室 A, B\n请携带门禁卡")

	// CATEGORIES 的两个元素是两个值；元素内部的逗号仍属于文本本身。
	event.Props.SetTextList(ical.PropCategories, []string{"研发,平台", "排期"})

	cal := ical.NewCalendar()
	cal.Props.SetText(ical.PropVersion, "2.0")
	cal.Props.SetText(ical.PropProductID, "-//Example//Calendar 1.0//CN")
	cal.Children = append(cal.Children, event.Component)

	var buf bytes.Buffer
	if err := ical.NewEncoder(&buf).Encode(cal); err != nil {
		// 编码器拒绝属性值中的原始 CR/LF，保留错误上下文便于定位输入源。
		return "", fmt.Errorf("编码日历: %w", err)
	}
	return buf.String(), nil
}

func main() {
	// 示例只展示生成策略；生产代码可把结果写入 HTTP 响应或 .ics 文件。
	text, err := buildCalendar()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(text)
}

这段代码的关键不是记住某个反斜杠数量，而是不要绕过 Prop 的文本 API。SetTextList 会在元素之间写入 TEXT 列表分隔逗号，同时对元素内部的逗号再做转义，所以“多个值”和“一个值中含逗号”能够区分开。

读取时用 TextList 判断“一个值”还是“多个值”

TextList 会按 TEXT 规则解析属性值，并把未转义的逗号当成多个元素；转义逗号则留在当前元素中。Text 调用同一套解析逻辑后只返回第一个元素，因此不适合用来确认一个属性是否携带了多个值。

func readCategories(cal *ical.Calendar) ([]string, error) {
	// Props.TextList 会还原 \\, \\;、\\, 和 \\n，并按未转义逗号拆分多个值。
	values, err := cal.Props.TextList(ical.PropCategories)
	if err != nil {
		return nil, fmt.Errorf("读取 categories: %w", err)
	}
	return values, nil
}

func readSummary(cal *ical.Calendar) (string, error) {
	// SUMMARY 约定为一个显示文本，使用 Text 可直接取得第一个值。
	return cal.Props.Text(ical.PropSummary)
}

如果输入里出现单独的反斜杠，或者出现 \\q 这类不在规则内的转义，TextList 会返回解析错误。这个错误应该保留给调用方，而不是静默删掉反斜杠；否则用户输入会被悄悄改写。

把属性值换行和物理折行分成两层

业务文本里的换行属于 TEXT 值，应该由 SetText 编码为 \\n。iCalendar 线过长时的物理折行则是另一件事：后续行以空格或制表符开头，解码器会把它们拼回同一条内容行。不要手动在业务字符串里插入 CR/LF 来模拟折行。

编码器还会拒绝属性值中真实存在的 CR 或 LF。也就是说，直接构造 Prop{Value: "标题\n第二行"} 与调用 SetText("标题\n第二行") 不是同一件事：前者把非法物理换行交给编码器，后者先变成合法的 TEXT 转义。

按输入、转义、解析和输出四个边界收口

当日历内容来自表单、接口或外部文件时，可以把排查固定成四个边界：

1. 输入边界：先把用户文本当作普通 Unicode 字符串，不自行替换逗号和反斜杠。
2. 转义边界：写入 TEXT 属性统一走 SetText 或 SetTextList，不要拼接 Prop.Value。
3. 解析边界：读取多值属性用 TextList，读取单值属性用 Text，并保留非法转义错误。
4. 输出边界：让 Encoder.Encode 负责输出 CRLF 和线格式；业务换行只能以 \\n 出现在属性值里。

如果问题表现为“标题被拆成两段”，先查有没有把逗号当成列表分隔；如果表现为“编码失败”，再查是否把真实 CR/LF 直接写进了 Prop.Value；如果表现为“反斜杠消失”，重点检查输入是否包含非法转义。这样比在生成后的 .ics 文本上反复替换字符更容易控制风险。

常见问题

SetText 和 SetTextList 应该怎么选？

一个完整显示文本用 SetText；属性语义确实包含多个 TEXT 元素时用 SetTextList。元素中的逗号仍由库转义，不要自己拼接。

为什么 Text 读不到第二个值？

Text 只返回解析后列表的第一个元素。要保留全部值，使用 TextList，再按业务语义检查列表长度。

业务换行和 iCalendar 折行是一回事吗？

不是。业务换行编码为 \\n；物理折行是过长内容的线级表示，由连续行开头的空格或制表符关联。不要用真实 CR/LF 代替业务换行。

总结

Go go-ical 处理逗号和换行的关键是让文本 API 负责线格式：SetText 适合单值，SetTextList 负责多个值，TextList 负责还原并拆分，Text 只取第一个值。把业务换行、列表分隔、非法转义和物理折行分成四个边界，日历内容就不会因为一个逗号或换行被错误改写。