@chenkunqing/note-image-export

English | 简体中文

用于在浏览器中把结构化笔记数据导出为 PNG 图片的工具包。

目录

• 功能概览
• 当前状态
• 安装
• 快速开始
• API
• 行为说明
• 本地开发
• 发布清单
• 不包含的内容

功能概览

这个包只做一件事：在浏览器里把“笔记形态的数据”渲染成一张可导出的 PNG 图片。

当前包含这些能力：

• 离屏渲染带独立样式的笔记卡片
• 基于 html-to-image 输出 PNG
• 优先复制到剪贴板，失败时自动降级为下载
• 支持清单、标签、表格、代码块和图片网格
• 通过注入函数适配你自己的富文本渲染和图片地址解析逻辑

当前状态

• 已整理到可单独发布 npm 包的状态
• 当前包名为 @chenkunqing/note-image-export
• package.json 的仓库信息已指向当前 monorepo 中的 packages/note-image-export
• 如果之后把这个目录拆到独立仓库，需要同步更新 repository、homepage 和 bugs

安装

npm install @chenkunqing/note-image-export html-to-image

为什么 html-to-image 需要单独安装：

• 这个包在运行时依赖它
• 它被声明为 peerDependencies，这样接入方可以自己控制版本

快速开始

import { exportNoteAsImage } from '@chenkunqing/note-image-export';

await exportNoteAsImage(
  {
    title: '周复盘',
    content: '<p>把包发出去。</p>',
    type: 'text',
    updatedAt: new Date().toISOString(),
    labels: [{ name: '工作' }],
  },
  {
    filename: 'weekly-review',
    renderContent: (content) => content,
    footerSource: 'My App',
  },
);

API

exportNoteAsImage(note, options?)

这个方法会先渲染笔记，然后：

• 优先复制为图片到剪贴板
• 如果当前环境不支持，就自动下载为 .png

常用选项：

• filename：导出文件名
• renderContent：把你项目里的富文本内容渲染成 HTML
• resolveImageSrc：把你自己的图片对象解析成浏览器可访问的地址
• updatedAtLabel：头部更新时间标签文案
• exportedAtLabel：底部导出时间标签文案
• footerSource：底部来源或产品名
• preferClipboard：传 false 时直接走下载

renderNoteToBlob(note, options?)

和上面的视觉渲染一致，但返回的是 PNG Blob，不直接复制也不直接下载。

适合这些场景：

• 你想自己上传导出的图片
• 你要接入自定义分享流程
• 你要做二次处理后再保存

NoteExportData

type NoteExportData = {
  title?: string;
  content?: string;
  type: 'text' | 'checklist';
  color?: string;
  updatedAt?: string;
  checklistItems?: Array<{ content: string; isChecked: boolean }>;
  labels?: Array<{ name: string }>;
  images?: Array<{
    filename?: string;
    localUrl?: string;
    src?: string;
    alt?: string;
  }>;
};

说明：

• content 只在 type: 'text' 时使用
• checklistItems 只在 type: 'checklist' 时使用
• images 可以直接提供 URL，也可以通过 resolveImageSrc 从业务对象转换

ExportNoteImageOptions

type ExportNoteImageOptions = {
  filename?: string;
  width?: number;
  baseFontSize?: number;
  pixelRatio?: number;
  backgroundColor?: string;
  updatedAtLabel?: string;
  exportedAtLabel?: string;
  footerSource?: string;
  preferClipboard?: boolean;
  skipFonts?: boolean;
  imagePlaceholder?: string;
  formatDate?: (iso: string) => string;
  isMobile?: () => boolean;
  renderContent?: (content: string, note: NoteExportData) => string;
  resolveImageSrc?: (image: NoteExportImage, note: NoteExportData) => string | null | undefined;
};

行为说明

• 这是一个纯浏览器侧包，运行时需要 window、document，如果要复制到剪贴板还需要可用的 Clipboard API。
• 富文本渲染没有写死在包里，应用可以通过 renderContent 注入自己的 HTML 或 Markdown 渲染逻辑。
• 图片地址解析同样可以通过 resolveImageSrc 自定义。
• 如果剪贴板复制不可用，会自动降级为下载。
• 这个包提供的是“笔记导出”场景下的默认视觉样式，但不会耦合 React、Vite、Zustand、Tiptap 或后端接口。

本地开发

npm install
npm run build
npm run check
npm run pack:preview

发布清单

1. 更新 package.json 里的 version。
2. 确认 name、repository、homepage、bugs 指向正确仓库。
3. 运行 npm run prepublishOnly。
4. 使用 npm publish --access public 发布。

不包含的内容

这个包目前不包含：

• React 组件
• 编辑器集成
• 状态管理
• 上传接口
• 笔记持久化

这些内容应该继续留在接入方应用里，通过 renderContent 和 resolveImageSrc 这类适配入口完成衔接。