Skip to content

README.zh-CN.md

Latest commit

 

History

History
181 lines (138 loc) · 4.92 KB

README.zh-CN.md

File metadata and controls

181 lines (138 loc) · 4.92 KB

@chenkunqing/note-image-export

English | 简体中文

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

目录

功能概览

这个包只做一件事：在浏览器里把“笔记形态的数据”渲染成一张可导出的 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 这类适配入口完成衔接。