简介calendar-link 是一份面向 Web 开发者的开源日历链接生成器源码包采用 TypeScript 编写能够一键生成 Google Calendar、Yahoo!、Microsoft Outlook、Office 365 以及 ICS 格式的事件链接解决在多个日历服务间手动拼接 URL、反复校验参数的痛点。压缩包共 28 个文件压缩后仅 139KB核心为 src 下的 TypeScript 源码、接口类型定义与单元测试同时包含 package.json、Jest 配置、语义化发布与 GitHub Actions 的 YAML 工作流以及 README 和变更日志等文档项目结构贴近正式开源库。阅读这份资源读者既能直接安装使用 npm 包快速接入会议邀请或日程提醒功能又能从类型声明、测试用例和模块导出中学习工具库的接口设计方法便于按需扩展对更多日历厂商的支持。已有 265 人学习下载适合有 JavaScript/Node.js 基础、正在开发日程管理或自动化效率工具的开发者。1. 日历链接生成器给添加到日历按钮补上最后一公里做过活动落地页、邮件模板或者课程通知的人应该都遇到过这个场景页面做完了按钮文案写的是添加到日历结果后端丢来三个平台的文档让你自己拼链接。Google Calendar 的 URL 是一套参数体系Outlook 是另一套Yahoo 和 iCal 又各玩各的同一场 14:00 的活动五个平台要拼五遍。calendar-link 是一个用 TypeScript 编写的日历链接生成库它把 Google Calendar、Outlook、Yahoo Calendar、iCal 以及 Office 生态的日历 URL 拼装逻辑收敛成统一入口你传一个事件对象进去它把各平台的链接一次性生成好顺带把编码和时区这些细节处理掉。适合写前端活动页、营销邮件、SaaS 后台通知的开发者不用为日历链接专门维护一套后端。2. 认识 calendar-link统一入口与多种服务商链接差异2.1 库解决的核心问题各服务商 URL 模板与字段名不统一日历链接这件事本身并不复杂复杂的是平台多了以后没人维护。我最早做某个内部活动系统的时候需要支持 Google Calendar 和 Outlook 两个平台后端同事写了两个函数每个函数一套字符串拼接逻辑。你以为写完就结束了第二个星期产品说还要支持 iCal 下载第三个星期又加了 Yahoo那段时间这个模块基本就是一个黑匣子谁都不敢碰。为什么会这样因为每个服务商的 URL 设计语言完全不一样// 手拼两个平台就已经是两套字段名 function dateToGoogleFormat(input: string): string { return input.replace(/[-:]/g, ).replace(T, ); } function buildGoogleCalendarUrl(event: Event) { const start dateToGoogleFormat(event.start); const end dateToGoogleFormat(event.end); return https://calendar.google.com/calendar/render?actionTEMPLATEtext${encodeURIComponent(event.title)}dates${start}/${end}; } function buildOutlookUrl(event: Event) { return https://outlook.live.com/calendar/0/deeplink/compose?subject${encodeURIComponent(event.title)}startdt${event.start}enddt${event.end}; }Google 用的是actionTEMPLATE加text加datesOutlook 用的是subject加startdt加enddtGoogle 的时间格式是紧凑的YYYYMMDDTHHMMSSOutlook 接受带横杠的YYYY-MM-DDTHH:MM:SS。这还只是两个平台而且我当时连encodeURIComponent都没加后来标题一出现就出问题。calendar-link 的核心思路就是把每个平台各自的 URL 规则收进一个纯函数。你只描述事件本身标题、开始时间、时长、地点、描述、时区剩下的 URL 差异、字段映射、百分比编码、全天事件和重复规则的格式转换都由库内部处理。它本身是用 TypeScript 写的所以调用方也能拿到完整的字段类型提示传错字段名在编译期就会报错而不是等链接生成出来才发现。这个库依赖很小不牵扯 UI 框架纯 JavaScript 环境也能跑所以放在前端工具函数、Node 脚本或者邮件模板的生成服务里都合适。它解决的不是生成一个链接这个小问题而是同时面向多个日历服务商时怎么让代码不变成一坨只有自己敢碰的字符串拼接。2.2 安装与最小可用示例生成第一个 Google Calendar 链接安装就是普通 npm 包流程npm install calendar-link装完之后在 TypeScript 或 JavaScript 项目里直接导入import { createCalendarLink } from calendar-link; const event { title: 团队季度复盘会, description: 讨论 Q3 数据回顾与 Q4 规划, start: 2026-03-20T14:00:00, duration: { hours: 1, minutes: 30 }, address: 3F 会议室, }; const googleLink createCalendarLink(event, google); console.log(googleLink);这里有三点值得展开。第一start传的是当地时间的 ISO 字符串不带时区后缀。库的工作方式是把start当成事件发生地的本地时间再用你额外传入的timezone字段去补充时区信息而不是从字符串里硬解析出偏移量。第二duration传的是{ hours: 1, minutes: 30 }对象而不是数字这是因为各个平台对时长表达不一致统一用对象能避免90到底是分钟还是秒的歧义。第三第二个参数google指定目标平台合法的取值通常包括google、outlook、yahoo、ics等。生成的链接会在浏览器或 Node 环境里以字符串形式拿到形如https://calendar.google.com/calendar/render?actionTEMPLATEtext%E5%9B%A2%E9%98%9F...dates20260320T140000/20260320T153000注意里面的中文已经被编码成了百分号形式。这是库内部统一编码的结果不要试图拿原始中文去拼 URL否则大概率会在某个平台的解析器上翻车。事件对象里比较常用的字段我一般会按这个类型去记忆interface CalendarEvent { title: string; start: string; // ISO 8601 本地时间或纯日期全天事件 duration?: { hours?: number; minutes?: number; seconds?: number }; allDay?: boolean; description?: string; address?: string; timezone?: string; // IANA 时区 ID如 Asia/Shanghai recurrence?: string; // RRULE 字符串 }这些字段里面title和start是必须的其余字段按场景补。只要把这个对象定义好整个页面所有按钮都可以复用同一份数据源不需要为某个平台单独维护字段。2.3 返回链接的可打开性与落地页差异链接生成后当然可以直接打开但不同平台的直接程度不一样。Google Calendar 的链接会先经过登录态判断已登录用户会进入带预填内容的新建事件页未登录则先跳登录Outlook 的链接会打开一个确认添加页Yahoo 的落地行为相对不稳定有时候点进去是新建事件表单有时候却是日历月视图这个跟服务端的会话状态有关不是链接格式问题。所以验收的时候一定要逐个平台实测不能只拿 Google 的链接验证完就认为四个平台都没问题。3. 按服务拆解Google、Outlook、Yahoo、iCal 的生成与参数映射3.1 Google CalendaractionTEMPLATE 与 dates/ctz 时间格式Google Calendar 的网页链接是所有服务商里最友好的一个因为它支持通过 URL 参数直接预填事件内容。核心模板是const event { title: 产品评审, start: 2026-04-08T10:00:00, duration: { hours: 1 }, timezone: Asia/Shanghai, address: Room 201, description: 评审新版交互稿, }; const googleLink createCalendarLink(event, google);生成的 URL 关键参数包括actionTEMPLATE表示这是新建事件模板text是标题details是描述dates是开始与结束时间location是地点ctz是时区。其中dates的格式是startYYYYMMDDTHHMMSS/endYYYYMMDDTHHMMSS比如20260408T100000/20260408T110000。这个紧凑格式来自 Google 对日历 URL 的约定注意中间那个T不能丢时和分秒必须是HHMMSS六位。这里最容易翻车的点是有人把带08:00偏移的时间字符串直接塞进去。dates字段在带ctz的情况下应该是20260408T100000/20260408T110000这样的裸本地时间一旦混入08:00部分版本解析器会把它当成非法格式或直接落成 UTC 显示时间凭空差了 8 个小时。库的做法是你传timezone字段它把时区放进ctz但由于不同版本的库对时区字段的处理细节有差异我建议生成后自己打印一次链接确认ctz确实存在而且值正确。Google 还有一个容易被忽略的点dates里的结束时间是从start duration推导出来的。如果你同时传了 duration 又手动改过 start要确认两次传参的数据源是同一条事件而不是各写各的。3.2 Outlook 与微软生态deeplink compose 与桌面端偏好Outlook 的链接跟 Google 走的是完全不同的设计路线。它不用一长串 query 预填而是用outlook.live.com/calendar/0/deeplink/compose作为入口把事件参数放进 path 后的 query 里const outlookLink createCalendarLink({ title: 客户演示, start: 2026-04-08T10:00:00, duration: { hours: 1 }, address: 线上会议, description: 演示新版本功能请提前 5 分钟入会, }, outlook);生成的链接形如https://outlook.live.com/calendar/0/deeplink/compose?subject%E5%AE%A2%E6%88%B7%E6%BC%94%E7%A4%BAstartdt2026-04-08T10:00:00enddt2026-04-08T11:00:00location...body...Outlook 的字段名和 Google 完全不同subject是标题、startdt是开始、enddt是结束、location是地点、body是描述。它的时间格式带横杠跟 Google 的紧凑格式又是两套规范。这就是为什么每家平台的手动拼接代码没法互用。需要注意enddt也是由 duration 推算的。库在这里内部做了一步换算把{ hours: 1 }变成开始时间精确计算后的结束时间。另外Outlook 链接对 URL 长度更敏感body字段一长整条链接很容易超过一些企业邮箱安全网关的长度限制这一点在 5.4 会单独再说。3.3 Yahoo Calendar 与 iCal下载兜底与邮件场景Yahoo Calendar 的链接体验一言难尽。生成是可以生成的但打开后不一定进新建事件页有时候跳到月视图。我第一次接入的时候也为此困惑过最后在项目里干脆做了一个降级策略桌面 Web 端主推 Google 和 OutlookYahoo 链接只作为兜底展示邮件里发活动邀请时直接改用 iCal 下载文件。iCal 的生成和其他平台不一样它产出的不是一段网页 URL而是一个data:协议链接点击后浏览器会下载data:text/calendar文件const icsLink createCalendarLink({ title: 季度总结会, start: 2026-04-08T10:00:00, duration: { hours: 2 }, address: 线上, }, ics); console.log(icsLink.startsWith(data:));这个.ics文件是日历领域的通用交换格式iOS 日历、Android 的 Google 日历 App、桌面 Outlook 都认它。移动端网页里直接放 Outlook 的 deeplink 经常不灵放 ics 下载链接反而稳。所以在做邮件模板时我一般只放两个出口Google 网页版链接加 ics 下载文件。不过也要注意部分邮箱客户端会拦截data:协议的链接邮件场景更稳妥的做法是把.ics作为附件或托管到静态资源服务器这里按你实际投放渠道取舍。3.4 地址、描述、时长在各服务中的参数映射把几个常见字段在不同平台里的落位整理成一张表排查时很有用事件字段GoogleOutlookiCalYahoo标题textsubjectSUMMARYtitle描述detailsbodyDESCRIPTIONdesc地点locationlocationLOCATIONin开始时间dates ctzstartdtDTSTARTst结束时间dates 推导enddtDTENDet时区ctz时间字符串或忽略TZID无独立字段这张表不需要背但需要有个概念当你怀疑某个字段没生效时第一步是确认字段有没有映射到目标平台正确的位置。比如在 Outlook 链接里找text参数注定找不到因为 Outlook 里根本没有text这个名字只有subject。常见误用是拿 Google 的参数文档去调 Outlook 的链接或者反过来。这跟库没关系纯粹是心智模式的问题。用 calendar-link 之后你不需要关心这些映射的细节但看链接定位问题时这张表就是你快速判断库有没有把事件转换对的依据。4. 进阶场景时区、全天事件与重复事件的正确姿势4.1 时区 ID 传参让邀请在各时区都显示正确时间时区是日历链接里最容易产生看着对了实际错了的字段。先明确一个原则start传事件发生地的本地时间时区通过timezone字段单独告诉库两者不要混在一个字段里。const event { title: 全球产品同步会, start: 2026-04-08T14:00:00, duration: { hours: 1 }, timezone: Asia/Shanghai, }; const googleLink createCalendarLink(event, google); const icsLink createCalendarLink(event, ics);这样生成的 Google 链接里时间字段是20260408T140000/20260408T150000ctz是Asia/ShanghaiiCal 文件里则体现为带TZIDAsia/Shanghai的DTSTART。接收者打开后日历客户端会按他自己的时区把 14:00 换算成本地时间这才是跨时区场景下期望的行为。我见过最典型的翻车是把 timezone 直接拼进 start 字符串比如传2026-04-08T14:00:0008:00又同时传timezone: Asia/Shanghai结果时间被当成 UTC 再套一次偏移等于加了两遍。正确做法永远只有一种时间字段保持朴素本地时间时区单独走timezone字段。还有一点要注意Outlook 的链接没有独立的时区参数它要么靠时间字符串里的偏移表达要么完全按浏览器本地时区解析。如果你面向的是跨多个时区的用户Outlook 链接的行为最不可控建议在邮件模板里对 Outlook 用户附上请按自己本地时区核对时间的提示。这不是 calendar-link 独有的限制是 Outlook 自身的协议如此。4.2 全天事件与跨天事件的 duration 处理全天事件是另一个高频踩坑点。如果按普通事件那样传00:00开始再加 24 小时 durationGoogle 会把事件显示成 0 点到 24 点的普通事件而不是一个全天的标签卡片。要触发全天的语义必须让时间字段变成纯日期const allDayEvent { title: 团队团建, start: 2026-05-01, allDay: true, };注意这里start是2026-05-01没有T00:00:00同时不传 duration。当库检测到纯日期字符串时它内部会把事件按全天语义输出Google 的dates变成20260501/20260502iCal 的DTSTART;VALUEDATE:20260501。结束日期多出来的一天是日历格式约定的表示这个日期区间包含开始日当天。我自己踩过的坑是全天事件传了 duration。当时图省事复用了普通事件的构造逻辑结果手机日历上显示的不是全天二字而是一条 00:00 到 23:59 的蓝色整块。从那以后我强制要求allDay为 true 时代码里显式注释不得传入 duration。跨天事件则按普通事件处理start 用第一天的时间duration 写总时长const multiDayEvent { title: 年度技术大会, start: 2026-06-01T09:00:00, duration: { hours: 24 * 2 }, // 跨 2 天最稳的折算方式 };有的版本支持days单位但我一般会用小时折算避免不同版本对days字段的兼容性差异。iCal 对跨天事件的结束时间是排他性的也就是说DTEND指向最后一天的结束时刻而不是其后一天。4.3 RRULE 重复事件字符串格式与各家兼容边界重复事件在日历链接里属于能生成但不保证所有平台都买账的特性。calendar-link 的recurrence字段接收的是 RRULE 字符串例如const weeklyEvent { title: 每周站会, start: 2026-04-01T09:30:00, duration: { minutes: 30 }, recurrence: RRULE:FREQWEEKLY;BYDAYMO,TH;COUNT10, }; const googleLink createCalendarLink(event, google);生成的 Google 链接会带上recurRRULE:FREQ%3DWEEKLY...这样的参数iCal 则会写进标准的RRULE属性。有几个约束必须背下来第一BYDAYMO,TH中间不要有空格空格会被解析成非法字符第二COUNT和UNTIL不能同时出现两个都传的时候不同平台会选择不同的那个结果不可预期第三RRULE 里的开始日期应该与事件的start保持一致如果不一致某些日历客户端会报规则与事件实例冲突。另一个实用细节Outlook 网页版对复杂 RRULE 的兼容性一般有些规则展示成不重复也没人知道。我通常的做法是Google 和 iCal 用完整 RRULEOutlook 链接用降级方案把重复事件当成普通单次事件生成同时在描述里补一句每周一、周四重复共 10 次。这样至少保证 Outlook 用户不会看到一个报了名却不会重复提醒的日历事件。5. 常见问题与避坑记录链接打不开、时间错位、参数丢失怎么办做日历链接看起来简单实际联调的时候问题都藏在平台差异里。这一章记录的是我在真实项目里踩过的五个坑每一条都按现象、原因、解决的排查思路整理基本都是没有查文档之前很难想到的那种。5.1 Outlook.com 链接在移动端静默失败现象桌面 Chrome 打开生成好的 Outlook 链接一切正常同一链接在手机微信内置浏览器或部分安卓 WebView 里点了没反应或者跳到一个白屏页面。原因Outlook 的 deeplink 依赖服务端会话与重定向链路部分移动端 WebView 对跨域重定向限制较严事件表单加载失败但不抛错用户看到的就是没反应。解决移动端优先给 ics 下载链接而不是 Outlook deeplink。我在按钮层做了设备判断移动端显示下载 .ics 日历文件桌面端才显示 Outlook 链接。判断方式极简navigator.maxTouchPoints 0就按移动端处理。这个方法不依赖具体浏览器厂商适用面广。5.2 描述里的换行与 字符被截断现象活动描述里写了两三行内容或者标题带研发与产品 运营这种文案生成链接后打开描述只剩第一行或者后面的内容显示成一段乱码参数。原因URL 的 query 里是参数分隔符换行符需要按 RFC 3986 编码成%0A。如果生成过程中任何一环用了未编码的字符串拼 URL或者手动去 decode 了一次再拼编码保护就失效。解决传给库的字段用原始字符串不要预编码。库会在内部统一做encodeURIComponent。如果生成之后你又做了字符串替换或拼接记得在最后对新增内容重新编码。排查方法是打印完整链接看两侧的参数分隔是否正常——一旦看到描述的换行变成了裸换行问题基本就定位了。5.3 时区 ID 与 UTC 时间双重换算导致偏移现象生成链接时传了timezone: Asia/Shanghai打开后事件显示为 15:00而不是期望的 14:00。原因时区 ID 本身出错率不高更多是时间字段带了 Z 后缀又传了 timezone的双重换算。当start是2026-04-08T14:00:00Z时它已经是 UTC 时间再按Asia/Shanghai显示自然就变成 22:00 或其它偏移而有的客户端解析ctz时还会再做一次本地化总的偏移量就成了双倍。解决时间与时区二选一。要传 timezone就传不带 Z 的本地时间要传 UTC就不传 timezone。项目里我加了检查逻辑禁止start.endsWith(Z)且同时存在 timezone 字段的配置出现从源头堵掉这个习惯。5.4 超长描述让链接超过客户端上限现象描述写了几百字链接生成后点击没有任何响应地址栏里链接很长。原因日历客户端的 URL 处理上限通常低于浏览器地址栏的 2048 字符有些网关对data:和 deeplink 还有额外限制。描述越长整条链接越容易超过这个阈值而被静默丢弃。解决描述控制在 300 字以内把长文放到详情页再让用户在描述里带一个短链接。如果描述里必须放大段内容就考虑不走链接直接生成 ics 文件.ics文件对长度不敏感。5.5 全天事件显示成 00:00 到 23:59 的普通事件现象全天活动生成后手机日历里显示00:00 - 23:59而不是全天标签。原因start 传了2026-05-01T00:00:00时间部分让日历客户端认为这是有具体时间的普通事件而不是全天事件。解决全天事件 start 传纯日期2026-05-01并显式加allDay: true。这个处理我第一次做的时候翻过车当时的判断依据是反正 00:00 开始不就是全天吗但实际上日历语义里完全不是这么理解的。6. 落到实战封装自己的 add-to-calendar 工具函数6.1 带兜底的厂商分发函数export function buildCalendarLinks(event: CalendarEvent) { const targets [google, outlook, yahoo, ics] as const; const links {} as Recordstring, string; for (const target of targets) { try { links[target] createCalendarLink(event, target); } catch (err) { console.warn([calendar-link] ${target} 生成失败, err); links[target] ; } } if (!links.google !links.ics) { throw new Error(calendar-link: 关键平台生成失败请检查事件字段); } return links; }这个函数的拦截逻辑是单个平台失败不阻塞整体但 Google 和 iCal 这两个最稳定的出口都失败时直接抛错避免调用方把空链接渲染进页面。返回值里每个 key 对应一个平台的完整链接调用方拿到后可以自己决定渲染哪些按钮。6.2 在 React 组件里缓存链接const calendarLinks useMemo( () buildCalendarLinks(event), [event.title, event.start, event.duration, event.timezone] );依赖项要写全事件字段否则改时间后用户拿到的还是旧链接。我在实际项目里就遇到过这种情况后台编辑把活动时间从 14:00 改到 10:00前台按钮链接还是 14:00因为依赖数组漏了event.start。如果不想维护依赖数组直接把整个 event 对象放进去也可以代价是每次父组件重渲染都会重新生成一遍链接量级不大时可接受。6.3 上线前验证四个链接逐个无痕打开生成完不是结束。我每次交付前都会做三件事先逐个服务商在无痕窗口打开链接确认都落到新建事件页而不是错误页或登录死循环再检查标题和描述里有没有或%残留导致的参数串位最后核对时间与时区是否一致尤其是全天事件和跨时区场景。这三个检查加起来不到十分钟但能把 5.2 到 5.5 里的大部分坑提前拦在门外。在那之后我接手每个活动页需求都会强制走一遍这个流程生成链接、逐个无痕打开、核对参数几分钟的成本换掉一整批日历链接客诉。希望帮到你。本文还有配套的精品资源点击获取