简体中文 · English

Magical Cards is a desktop Obsidian plugin for book, film, and image showcase cards, with draggable modules and note embeds. It works offline with six editable starter examples. The interface is currently in Chinese; see the full English guide.

Magical Cards

把阅读、观影与图片收藏，变成可以浏览、编辑、嵌入笔记的卡片。

下载插件 · 使用说明 · 更新日志 · 反馈问题

作者惯用卡片风格（该插件提供多种样式供选择）：

已上传Obsidian社区，我会不定时维护和更新，欢迎体验插件，希望你喜欢～ https://community.obsidian.md/plugins/magical-cards

插件的开发思路

我开发了一个自己用的工作台，最近改造到obsidian里后发现，这个卡片轮播的视觉效果出奇的好，大大提高了我的记录动力，不得不说颜值是第一生产力。 以前经常想要写读书笔记、观影笔记，最后总因为笔记长期维护难度大，反馈小而拖延放弃，而这个卡片轮播像集卡收藏一样， 书籍影视就这么美丽地展现到我面前，我一回忆起曾经阅读或者观看的画面就忍不住点击进入笔记写上一两句作为记录。

进一步思考，我想到这个卡片轮播也可以单纯的只展示不记录，于是新增了橱窗功能，大家喜欢的照片、角色、明星等可以通过用橱窗功能，呈现在Magical Cards窗口以及你的任意笔记里。

这个插件是从我的Obsidian工作台里独立出来的，等我的工作台开发完善了我会带它和大家见面。关于这个插件，如果你有任何建议和反馈，欢迎给我提issue,或者作为contributor参与进一步开发我的插件，你也可以fork我的插件去自定义你的功能。

传送门:https://github.com/AbigBlackCat/Obsidian-Magical_Cards/

Installation

Requires Obsidian desktop 1.11.4 or later. In Settings → Community plugins → Browse, search for Magical Cards, install and enable it. Community listing.

For manual installation:

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Put all three files in <vault>/.obsidian/plugins/magical-cards/.
3. Reload Obsidian and enable Magical Cards in Settings → Community plugins.

Usage

On first use in an empty card directory, the plugin creates six offline examples and opens a guide. Open the cards view from the ribbon icon or the 打开卡片视图 command. To embed collections in a note, run 插入卡片模块 and select existing modules; the command inserts the code block into the active note. Settings also provides a generator for copying and pasting the code. See README_en.md for the complete guide.

目录

• 开始使用
• 功能
• 外观与设置
• 嵌入笔记
• 常见问题与数据
• 开发与版权

开始使用

首次在空目录启用，插件会在 卡片库 中创建说明页、3 本书与 3 部影视，并自动打开说明页。六张封面随插件打包，断网也能查看；示例作品可以编辑或删除。

起步外观为 圆柱弧面、整幅封面、填满裁切、纸感、2:3、同屏最多三张卡片。滑动或使用方向键，仍可浏览全部六张作品。

1. 打开卡片：点击侧栏卡片图标，或执行「Magical Cards: 打开卡片视图」。
2. 添加作品：点击模块右上角的 +，填写标题、封面及作品信息。
3. 记录感想：翻到卡片背面编辑摘要，或打开关联的作品笔记。

再次查看说明，执行「查看示例及用法说明」。初始化中途失败也可通过此命令重试。已有卡片库不会重复导入示例，也不会修改原外观；删除示例后重启不会补回。

功能

Dashboard 分类

Magical Cards 标签页顶部的“全部”展示所有未隐藏模块。点击右侧 + 新建 Dashboard，填写名称、勾选要展示的已有模块，再点击“保存 Dashboard”。新建时全部未勾选；新模块也不会自动加入分类。同一模块只有经你主动勾选，才会出现在多个 Dashboard，笔记和图片共用一份。

切换到分类后，点击“编辑 Dashboard”调整名称和成员；删除 Dashboard 仅删除分类，保留模块、笔记和图片。每个 Dashboard 的模块顺序单独保存，“全部”的顺序也独立保存。分类操作使用原有模块的稳定 ID，不改动作品笔记或已有笔记嵌入的集合引用与局部顺序。

设置中的模块垃圾桶是全局隐藏：该模块会从“全部”和所有 Dashboard 中隐藏；恢复后仍保留原分类与顺序。若提示当前共享运行时不支持 Dashboard，请升级已启用的兼容卡片插件并重启笔记库；原有模块和资料会保留。

五种动效布局

封面流轮播	黑胶专辑架
横向滚动弯曲画廊	倾斜轮播

圆柱弧面见首页预览。滚动弯曲画廊还支持竖向：

外观与设置

设置依次为：卡片目录 → 示例 → 添加卡片模块 → 添加图片橱窗 → 已有模块 → 已移除模块 → 笔记代码块生成。两个添加入口、示例、已有模块、已移除模块和高级设置默认收起。

按用途展开“添加卡片模块”或“添加图片橱窗”，只需填写模块名称、选择比例，然后点击保存并收起。两个入口的类型固定、草稿独立；高级样式仅选择整幅封面或简约，不转换存储类型。保存后点击左侧紫色叠卡图标，在 Magical Cards 标签页体验。设置中的预览仅能浏览和滑动，不会翻面或打开描述编辑。

“高级设置”依次包含：卡片样式 → 显示方式 → 卡片材质 → 动效布局 → 仅显示三张卡片。弯曲画廊才显示方向。新模块预设为 整幅封面、填满裁切、纸感、2:3、倾斜轮播、关闭仅三张；阅读／影视示例和已有模块保留原外观。三卡选项分别作用于各模块，仍可浏览全部图片。

模块展开后，标题右侧的垃圾桶只移除展示，保留配置、顺序、笔记和图片。展开“已移除模块”可恢复。保存失败或来源冲突时保留草稿，检查后重试或重新载入。

卡片目录填写当前笔记库内的相对目录，例如 卡片库。作品保存在其下的 书籍／观影 目录，橱窗在 橱窗/<模块 ID>/，配置保存在 _数据/卡片配置.md。切换目录不会搬运原有作品；不要填写电脑上的绝对路径。

图片橱窗

橱窗适合只展示图片的收藏。在设置中展开独立的添加图片橱窗，填写名称、选择比例并保存。此入口始终创建橱窗，已有作品模块不转换为橱窗。保存失败时保留草稿与已经创建的橱窗笔记，重试不会重复建笔记。

图片正面	翻面描述

• 点击橱窗的添加图片按钮批量选择图片，也可拖入图片。不会自动扫描文件夹；支持 PNG、JPEG、WebP、GIF、SVG，每张最大 10 MB。
• 每个橱窗独用一个文件夹与一篇 橱窗.md，导入图片复制到该文件夹。打开笔记即可看到全部图片、可选名称与描述。图片名称可以留空。
• 高级设置可关闭翻面，或把名称放在正面、背面、不显示。默认开启翻面、名称放在背面，正面聚焦图片。正面名称模式的背面仅显示描述；不显示名称会保留已填写文字。
• 背面描述为最多 400 字纯文本，自动保存；输入法输入期间等待确认，冲突或失败保留草稿并提供重试。关闭翻面后仍可通过“编辑当前图片”或共享笔记修改资料。
• 删除单张卡片仅移除其笔记区块，图片文件保留。图片顺序也保存在共享笔记中；修改目标字段和排序保留其他区块及未知属性。请保留卡片 ID 和管理标记。笔记缺失或标记损坏时提示修复，不会重建空笔记。
• 导入部分失败时，已保存的图片和稳定 ID 保留；在当前笔记库保持打开期间点击重试，不会重复加入成功的图片。请在关闭笔记库或停用最后一个共享卡片插件前重试；完整重启后重新选图属于新导入，可能产生重复卡片，原图片文件仍保留。

嵌入笔记

展开设置中的「笔记代码块生成」，选择一个或多个已有模块，然后生成并复制代码，粘贴进笔记即可。也可在笔记内执行「插入卡片模块」命令，选择模块后直接插入代码块。每次生成新的代码块 ID 和模块实例 ID；引用原作品，默认继承集合设置。

```magical-cards
id: reading-and-films
modules:
  - id: reading-instance
    collection: book
  - id: films-instance
    collection: film
```

同一集合可以出现在多篇笔记中。嵌入中的模块顺序只影响该代码块；排序原子更新 modules 数组，保留其余正文。重复 ID、源码冲突或未保存的原生编辑会阻止覆盖并保留草稿。复制代码到同一笔记时，请重新生成 ID。

常见问题与数据

开启三卡后，其他作品会消失吗？

不会。同屏最多显示当前卡和两张邻卡；仍可浏览全部作品，作品数量不会改变。

封面为什么留边？

「完整显示」保留图片全部内容，比例不同时可能留边；「填满裁切」贴满卡片，会裁切部分图片。原图自身的白边属于图片内容，插件会保留它。

数据保存在哪里？

作品是卡片目录中的普通 Markdown 笔记；外观与模块顺序保存在 _数据/卡片配置.md。插件本地配置保存目录、首次体验状态及必要恢复信息。切换目录不会重新导入示例或迁移原作品。

修改外观后标签页黑屏怎么办？

先等待保存完成，再退出并重新启动 Obsidian，打开原笔记库。外观已保存，作品和图片保留；修改现有模块外观时也会显示这条恢复提示。

是否联网或读取剪贴板？

插件不连接账户，不执行联网同步。内置示例离线可用；自行填写远程封面 URL 时会向相应图片服务器加载资源。「复制」只在用户点击后写入生成的代码；关联笔记选择器搜索笔记库中的笔记路径，不向外发送笔记内容。

可以在手机上使用吗？

目前仅支持桌面版。原生验收使用 macOS；Windows 尚未实机验证。插件界面目前为中文。

0.3.0 更新：新增橱窗式卡片，支持批量图片、可选名称与翻面描述；模块设置简化为名称和比例，高级项默认收起，三卡分别按模块设置；阅读、影视和自定义模块可移除展示并恢复，保留原数据和顺序。设置预览仅供浏览，编辑请使用左侧紫色卡片图标打开 Magical Cards 标签页。

0.3.1 更新：修正弯曲画廊退出时的 WebGL 上下文释放，比例和方向变化复用画布；首次说明页采用作者修订的正文；新建橱窗的选项改为“添加图片橱窗”；补充外观更改后的黑屏恢复提示。

0.4.0 更新：添加卡片模块与添加图片橱窗分为独立折叠入口，各自保留草稿；卡片标签页新增“全部”和 Dashboard 分类，可主动选择已有模块、编辑或删除分类，并分别保存模块顺序。分类共用原资料，新模块不自动加入，模块隐藏仍全局生效。

开发与版权

示例笔记库 仅包含三本书、三部影视及独立示例 ID；安装三个插件文件后用 Obsidian 打开即可。其卡片目录为「示例」。说明页模板 用于首次体验。

npm ci
npm run lint
npm run typecheck
npm test
npm run build

浏览器开发预览：npm run preview，打开 http://127.0.0.1:4319。原生验收与平台限制见 VERIFICATION.md，社区审核进度见 COMMUNITY.md。

代码采用 MIT。第三方封面及含封面的预览图不受代码许可证授权，其权利归各自权利人；请保留封面来源与版权。布局、React 及构建适配说明见 THIRD_PARTY.md。