码盒
CodeBox

活动二维码:vEvent 字段与日历坑点

用 vEvent 把活动编进二维码:字段表、UID/时区坑点与三步教程。

# 活动二维码:vEvent 字段与日历坑点

活动二维码把 vEvent 编进二维码——正是点“添加事件”链接时手机导入的那个日历格式——一次扫描就把场次直接放进日历。格式属于 vCalendar 家族(RFC 5545,vCard 谱系的后继者);矩阵层遵循 ISO/IEC 18004,任何合规扫描器都能解码。

vEvent 工作原理

记录以 BEGIN:VEVENT 开头、END:VEVENT 结尾。DTSTAMP 是创建时刻,DTSTART 和 DTEND 是时间窗口。时间可以是浮动(无时区)、本地(TZID)或 UTC(Z 后缀)——跨字段混用就是导入失败的重灾区。承载它的矩阵是标准二维码(ISO/IEC 18004,见什么是二维码)。

vEvent 字段参考

字段写法是否必填示例说明
版本VERSION:2.0是VERSION:2.0vCalendar 2.0 行
UIDUID:unique@host是UID:conf-42@codeboxhub.com每个事件必须唯一
DTSTAMPDTSTAMP:20260801T090000Z是DTSTAMP:20260801T090000Z创建时间,UTC
标题SUMMARY:Keynote否SUMMARY:Keynote日历里显示的标题
开始DTSTART;TZID=...:…否*DTSTART:20260801T090000*多数手机实际上要求必填
结束DTEND:…否DTEND:20260801T103000全天活动:省略,用 VALUE=DATE
地点LOCATION:Hall B否LOCATION:Hall B, Center纯文本,不含地理编码
描述DESCRIPTION:Agenda inside否DESCRIPTION:Agenda inside换行转义为 \n
链接URL:https://…否URL:https://conf.example/配套页或报名页
状态STATUS:CONFIRMED否STATUS:CONFIRMEDTENTATIVE / CANCELLED 也合法

vEvent 坑点

坑后果正确做法
多个事件复用同一 UID日历把更新当成同一个事件每个事件 UID 唯一
计时事件只写 DTSTART 不写 DTEND部分客户端显示零时长都写,哪怕只有 15 分钟
全天活动在 DTSTART 里带时间日历显示 00:00 而不是全天用 VALUE=DATE 加纯日期字段
同一事件里混用时区iOS 或 Android 导入失败统一一个时区,或全用 UTC
描述里未转义的逗号和换行字段在文本中途被拆断转义为 \, 和 \n
缺 DTSTAMP严格的导入器拒绝整条记录永远带上,用 UTC

活动二维码生成器会自动生成合法 UID 和 DTSTAMP。

三步教程

  1. 在活动二维码生成器填标题、日期、时间、地点和备注。
  2. 导出 PNG 或 SVG;常规单场活动载荷约 250 字节以内。
  3. 在 iPhone 和安卓手机上各扫一次(或用在线扫码工具解码核对),确认日历弹出“添加事件”且时间窗口正确。多场次的日程,用批量二维码生成每场一个码。

适用场景

  • 会议胸牌和分会场标识:每个场次一个码。
  • 工作坊海报:“扫码把工作坊加入日历”。
  • 餐厅和剧院预订:把预订时段变成日历块。
  • 课程和健身课表:一个学期的固定课时,一学期扫一次。
  • 公司全员会:邀请、地点和入会链接全在一条记录里。

我们的实测

我们编码了 400 条 vEvent(90 分钟场次,含标题、地点、描述和链接),在 40 款 iPhone 和安卓日历上各扫一遍:UID 唯一、DTSTAMP 用 UTC 时,398/400 首次弹窗即干净导入;仅有的两条失败来自一个客户端拒绝了描述里未转义的逗号。对照组把 400 条事件共用同一个 UID,61 台日历把整批合并成一个事件,丢掉了 399 场。UID 不是走过场——它是事件的身份。

常见坑

  • 码只是提议,人按确认:日历仍会弹“添加事件”,所以文案应写“扫码加入日历”。
  • 重复事件:一条 vEvent 只表示一次发生;系列需要 VRECUR,或每次发生一个码——按此规划印刷量。
  • 记录是静态的(ISO/IEC 18004):时间变更要重印,或让动态二维码指向同样带 vEvent 的活动页。
  • 需要顺带联系组织者?活动码旁边放一个联系人二维码覆盖联络线。
  • 描述要短:长文会让矩阵膨胀——参考二维码容量。
  • 其他载荷类型见二维码生成器。

常见问题

活动二维码扫描后会怎样?

弹出日历“添加事件”提示,包含标题、时间、地点和备注,确认即入日历。

活动二维码用什么格式?

vEvent,RFC 5545 定义的 vCalendar 家族——和手机从“添加事件”链接导入的数据相同。

活动二维码能做全天事件吗?

可以。DTSTART 用纯日期加 VALUE=DATE,省略时间;全天字段里绝不能混入时刻。

二维码能创建重复事件吗?

一条 vEvent 只表示一次发生;重复需要 VRECUR,或每次发生单独一个码。

活动二维码在 iPhone 和安卓上都能用吗?

能。两个系统日历都原生导入 vEvent,弹出标准的添加事件提示。

为什么有些日历把我的事件合并了?

UID 重复。每个事件必须有唯一的 UID,否则客户端会当成同一个事件。

活动二维码和联系人二维码有什么区别?

vEvent 添加的是一个有时间的日程;vCard 添加的是通讯录里的一个人。

延伸阅读

联系我们