CalDAV是建立在WebDAV之上的协议，专门用于访问远程日历资源。很多日历服务，比如Nextcloud、iCloud以及部分Google Calendar场景，都通过CalDAV暴露数据。如果想把这些日历内容渲染成图片，就需要完成三个核心步骤：从CalDAV服务器获取iCalendar原始数据、解析其中的事件信息、再把事件按时间布局绘制成图像。下面直接从数据获取开始，逐步给出可运行的Node.js实现。
一、CalDAV数据获取：认证与REPORT查询
CalDAV协议本质上是对WebDAV的扩展，它使用HTTP方法操作日历资源。要获取某个时间范围内的事件，通常会先通过PROPFIND发现用户的日历集合地址，再向具体日历发起REPORT请求，并附带一个calendar-query的XML主体来限定时间段。对于Node.js开发者来说，手写这些XML并不划算，社区里已经有封装好的库可用，其中tsdav是使用比较广泛的一个。
安装依赖只需要执行npm install tsdav。下面的代码展示了如何创建CalDAV客户端、获取日历列表，并对第一个日历发起事件查询。查询的时间范围被设置为当前月份，这样可以减少返回的数据量。
const { createDAVClient } = require('tsdav');
async function fetchEvents() {
const client = await createDAVClient({
serverUrl: 'https://caldav.ipipp.com/remote.php/dav',
credentials: {
username: 'your-username',
password: 'your-password'
},
authMethod: 'Basic',
defaultAccountType: 'caldav'
});
// 获取日历集合列表
const calendars = await client.fetchCalendars();
console.log('找到日历:', calendars.map(c => c.displayName));
// 取第一个日历，查询本月事件
const targetCalendar = calendars[0];
const now = new Date();
const start = new Date(now.getFullYear(), now.getMonth(), 1).toISOString();
const end = new Date(now.getFullYear(), now.getMonth() + 1, 0, 23, 59, 59).toISOString();
const events = await client.fetchCalendarObjects({
calendar: targetCalendar,
timeRange: {
start: start,
end: end
}
});
return events;
}
这段代码中的fetchCalendarObjects方法内部会构造REPORT请求，并自动处理XML解析。返回的events数组里每一项都包含url和data字段，其中data就是原始的iCalendar文本。需要注意的是，CalDAV服务器的认证方式可能不同，部分服务要求使用OAuth2，需要调整authMethod和credentials的配置。
实际使用时还要考虑时区问题。iCalendar数据中的时间往往带有时区标识或者以UTC存储。在发起查询前，最好把时间范围统一转换为UTC，避免因为服务器本地时区不同导致漏掉边界事件。另外，如果日历数量很多，可以先通过PROPFIND读取current-user-principal来定位默认日历，减少不必要的遍历。
二、解析iCalendar：从ICS到结构化事件
拿到原始iCalendar文本后，需要把它解析成可以程序处理的结构。iCalendar格式使用BEGIN:VEVENT和END:VEVENT块表示事件，内部属性包括DTSTART、DTEND、SUMMARY、LOCATION以及可选的RRULE重复规则。Node.js生态中ical.js是一个成熟的选择，它由Mozilla开发，能够完整处理RFC 5545中的各种细节。
下面的代码演示了如何把上一步获取的iCalendar文本解析为事件对象数组。每个事件对象只保留绘制图片所需的字段，并且把时间统一转换为Date类型。
const ICAL = require('ical.js');
function parseEvents(calendarObjects) {
const result = [];
for (const obj of calendarObjects) {
const jcalData = ICAL.parse(obj.data);
const comp = new ICAL.Component(jcalData);
const vevents = comp.getAllSubcomponents('vevent');
for (const vevent of vevents) {
const event = new ICAL.Event(vevent);
result.push({
uid: event.uid,
summary: event.summary || '(无标题)',
location: event.location || '',
startDate: event.startDate.toJSDate(),
endDate: event.endDate.toJSDate(),
description: event.description || ''
});
}
}
return result;
}
这里使用ICAL.Event包装VEVENT组件，它能自动处理DTSTART和DTEND的类型差异。比如有些事件只有DTSTART而没有DTEND，ical.js会根据DURATION或者默认持续时间推算出结束时间。对于重复事件，event.startDate和event.endDate默认返回第一次发生的时间，如果需要展开具体某次重复，需要使用event.iterator()按规则生成。
时区是解析阶段最容易被忽略的坑。如果iCalendar数据中的时间带有TZID=Europe/Berlin这样的时区标识，ical.js会尝试使用内置的时区信息进行转换。但如果服务器返回的是自定义时区定义，可能需要手动注册ICAL.TimezoneService。为了稳妥，可以在解析完成后把所有时间统一转为UTC，并在绘制时再按目标时区显示。
三、用node-canvas绘制日历图片
绘制日历图片需要选择一个能在Node.js环境中使用的Canvas实现。node-canvas提供了与浏览器Canvas 2D API几乎一致的接口，并且可以导出PNG或JPEG。对于周视图布局，可以先把一天划分为24个小时格，计算每个事件的top和height，再按事件所在星期列水平定位。
下面这段代码实现了一个简单的周视图绘制函数。它接收解析后的事件数组，以及目标周的开始日期，然后生成一张800x600的PNG图片并保存到磁盘。
const { createCanvas } = require('canvas');
const fs = require('fs');
function renderWeek(events, weekStart) {
const width = 800;
const height = 600;
const canvas = createCanvas(width, height);
const ctx = canvas.getContext('2d');
// 背景
ctx.fillStyle = '#ffffff';
ctx.fillRect(0, 0, width, height);
// 绘制时间网格
const leftMargin = 60;
const topMargin = 40;
const dayWidth = (width - leftMargin) / 7;
const hourHeight = (height - topMargin) / 24;
ctx.strokeStyle = '#e0e0e0';
ctx.lineWidth = 1;
for (let hour = 0; hour <= 24; hour++) {
const y = topMargin + hour * hourHeight;
ctx.beginPath();
ctx.moveTo(leftMargin, y);
ctx.lineTo(width, y);
ctx.stroke();
}
// 绘制事件块
for (const event of events) {
const dayIndex = Math.floor((event.startDate - weekStart) / (24 * 60 * 60 * 1000));
if (dayIndex < 0 || dayIndex > 6) continue;
const x = leftMargin + dayIndex * dayWidth + 2;
const y = topMargin + (event.startDate.getHours() + event.startDate.getMinutes() / 60) * hourHeight;
const blockHeight = (event.endDate - event.startDate) / (60 * 60 * 1000) * hourHeight;
ctx.fillStyle = '#4a90d9';
ctx.fillRect(x, y, dayWidth - 4, Math.max(blockHeight, 4));
ctx.fillStyle = '#ffffff';
ctx.font = '12px sans-serif';
const text = event.summary.length > 12 ? event.summary.slice(0, 12) + '…' : event.summary;
ctx.fillText(text, x + 4, y + 14);
}
const buffer = canvas.toBuffer('image/png');
fs.writeFileSync('calendar-week.png', buffer);
console.log('图片已生成: calendar-week.png');
}
这段代码只处理了单行文本截断，实际项目中还需要考虑事件跨天、全天事件、重叠事件等复杂情况。跨天事件可以拆分为多个片段分别绘制，全天事件则放在日期标题下方单独一行。颜色方面可以根据日历分类或者事件状态动态选择，让图片更具可读性。
另一个常见问题是长文本显示不完整。上面使用了简单的字符截断，但中文字符宽度和英文字符不同，更好的做法是测量文本宽度后再进行截断。此外，如果事件之间的间距太小，可以设置最小高度并调整绘制顺序，避免重要事件被完全遮挡。
四、整合完整流程与优化建议
把前面三个步骤串起来，就可以搭建一个完整的CalDAV图片生成服务。核心流程是：认证客户端、查询日历集合、获取指定时间范围的iCalendar数据、解析为事件数组、调用渲染函数生成PNG。为了让代码更健壮，建议把认证信息放在环境变量中，不要硬编码在源码里。
性能方面，如果日历数据量很大，可以考虑增加缓存层。比如把解析后的事件按日期范围缓存到内存或Redis中，避免每次生成图片都重新请求CalDAV服务器。另外，node-canvas的PNG导出相对耗时，可以异步执行，避免阻塞事件循环。
安全上要注意CalDAV凭据的保护。如果这个服务需要对外提供HTTP接口，必须加上身份验证和访问控制，防止任何人通过接口拉取你的日历数据。对于自签名证书的CalDAV服务器，还需要在请求时传入自定义的HTTPS agent。
最后，这套方案不仅可以生成周视图，还可以扩展为月视图、日视图或者列表式卡片。只要把渲染函数中的坐标计算逻辑替换掉，就能输出不同风格的日历图片。整个过程完全在Node.js中完成，非常适合集成到自动化报告、团队通知机器人或者个人日程备份工具中。