README file from
GithubMagical Cards
已上传Obsidian社区，我会不定时维护和更新，欢迎体验插件，希望你喜欢～ https://community.obsidian.md/plugins/magical-cards
Magical Cards 是桌面和手机上的 Obsidian 卡片插件，用于浏览、编辑和嵌入书籍、影视与图片橱窗。作品保存在自己的 Markdown 笔记中，六张可编辑示例封面随插件提供，断网也能开始使用。插件界面目前为中文。
从 0.9.0 起，完整源码在私有仓库维护；本公开仓库继续提供安装更新、使用文档及 Issues。个人与企业可免费正常使用，许可与再分发限制见使用许可。
目录
开始使用
需要 Obsidian 1.11.4 或更新版本。在「设置 → 第三方插件 → 浏览」搜索 Magical Cards，安装并启用。手动安装时，从最新 Release 下载 main.js、manifest.json、styles.css，将三个文件放入 <笔记库>/.obsidian/plugins/magical-cards/，重新加载 Obsidian 后启用插件。
首次在空目录启用，插件会在 卡片库 中创建说明页、3 本书与 3 部影视，并自动打开说明页。六张封面随插件打包，断网也能查看；示例作品可以编辑或删除。
起步外观为 圆柱弧面、整幅封面、填满裁切、纸感、2:3、同屏最多三张卡片。滑动或使用方向键，仍可浏览全部六张作品。
- 打开卡片：点击侧栏卡片图标，或执行「Magical Cards: 打开卡片视图」。
- 添加作品：点击模块右上角的
+，填写标题、封面及作品信息。 - 记录感想：翻到卡片背面编辑摘要，或打开关联的作品笔记。
再次查看说明，执行「查看示例及用法说明」。初始化中途失败也可通过此命令重试。已有卡片库不会重复导入示例，也不会修改原外观；删除示例后重启不会补回。
功能
| 功能 | 操作 |
|---|---|
| 浏览与搜索 | 滑动、滚轮或方向键切换卡片；点击放大镜搜索作品。 |
| 管理作品 | 添加、编辑封面和信息、关联笔记、删除作品、调整排序。 |
| 翻面摘要 | 翻到背面记录感想；布局切换保留当前卡和摘要草稿。 |
| 图片橱窗 | 每个模块共用一篇笔记，批量导入图片、可选名称及翻面描述。 |
| Dashboard 分类 | 在顶部切换同等分类、拖动分类标签；在设置选择已有模块，各分类独立排序。 |
| 微信读书书目导入 | 在设置保存 API Key，读取书架并勾选要导入到书籍模块的书目。 |
| 模组作品 Dashboard | 点击模块菜单中搜索左侧的传送图标，查看该模块的统计、最近更新、搜索、筛选、临时排序与封面墙。 |
| 模块排序 | 拖动标题前的手柄；键盘聚焦手柄后按 Alt / Option + ↑ / ↓。 |
| 笔记嵌入 | 阅读模式和实时预览均可展示集合，同一集合可以重复引用。 |
Dashboard 分类
Dashboard 用来分类卡片模块，每个分类同等，可以放入任意数量的模块。同一模块可主动加入多个分类，笔记和图片仍共用一份。标签页没有固定“全部”页；未分类模块保留在设置中，仍可嵌入笔记。
打开标签页的横向操作菜单，可以新建、重命名或删除 Dashboard。删除分类只删除分类引用，保留模块和资料。拖动顶部标签，或聚焦后按 Alt / Option + ←、→，可以调整分类顺序；每个 Dashboard 内的模块顺序独立保存。
模块归属统一在插件设置中管理：
- 放入 Dashboard：展开模块，选择已有分类，也可新建分类并随模块一起保存。新建模块不选择分类时，先留在设置中。
- 移出 Dashboard：所属分类右侧的退出箭头只移出该分类，其他分类和笔记嵌入继续显示。
- 删除模块：展开标题右侧的垃圾桶删除模块配置、全部分类引用及模块位置。作品笔记、橱窗笔记、图片和作品 ID 保留；原嵌入会提示模块已删除，没有模块恢复入口。
- 删除当前卡片／图片：在模块横向菜单中操作，仅针对当前单张卡片。删除前确认窗口会明确显示名称。
新用户首次安装会得到可改名、可删除的普通“示例” Dashboard，包含阅读和影视。
模组作品 Dashboard
点击模块菜单中搜索左侧的传送图标，展开该模块的全部作品。在 Magical Cards 分类页内打开时，使用当前标签页；从笔记嵌入打开时，复用同一窗口已有的 Magical Cards 标签页，没有时新建。页面顶部只有「返回」与模组名称，搜索、筛选、临时排序和封面比例继续沿用原有行为；临时排序不改写模块保存的顺序。
点击「返回」恢复来源页面的滚动位置与传送入口焦点。来源已经关闭，或重启后恢复作品页时，返回 Magical Cards 分类页。自定义卡片优先打开关联笔记，图片橱窗打开模块笔记；书籍、影视和橱窗的既有字段与封面行为保留。
插件设置中的「启用模组作品 Dashboard」默认开启，只保存在本机插件配置中。关闭后各处传送入口立即隐藏，已经打开的作品页显示关闭提示，仍可返回。已有安装升级后首次加载会打开 Magical Cards 设置并显示本版本更新说明；关闭或点击「知道了」后记为当前版本已读。全新安装继续显示原有示例引导。本次无需迁移作品数据，也不改变 Dashboard 分类配置。
五种动效布局
| 封面流轮播 | 黑胶专辑架 |
|---|---|
 |
 |
| 横向滚动弯曲画廊 | 倾斜轮播 |
 |
 |
微信读书书目导入
在「设置 → Magical Cards」展开默认收起的「微信读书」：
- 打开获取 API Key，按微信读书指引获取密钥。粘贴后点击「保存授权」；成功后输入框清空，不会回显密钥。
- 点击「读取书架」，按书名或作者搜索并勾选书目。电子书与有声书均可导入，默认不勾选任何书目。
- 选择目标书籍模块，点击「导入所选」。未选择时使用内置阅读模块，并显示它当前的名称。若该模块已删除，需要选择有效目标；不会自动恢复模块。
目标只提供内置阅读与普通书籍模块。新建普通模块时可选择「作品类型：影视／书籍」，默认影视；已有模块不支持类型转换。同一模块已有的相同来源书目会跳过，保留所有手工内容；同一本书可在不同模块保留独立笔记。手工添加且没有来源标识的同名作品不会自动匹配。
失败书目保留勾选，可直接重试；成功或已存在的书目取消勾选。导入时不能修改授权、目标或卡片目录，关闭设置后已开始的导入会继续，插件停用或目标删除时停止后续写入。选择、目标和书架列表只保留在当前设置会话中。
密钥仅存于 Obsidian SecretStorage 独立槽位，不写入插件配置、卡片配置或作品笔记。仅在点击「读取书架」时向微信读书官方接口请求当前书架，不自动同步，不请求划线、想法、阅读时长或逐书详情，不创建文章收藏入口卡片。源中缺失的摘要、个人评分及其他资料保持为空。有声书的「已完结」不会被当作你的「已读」。
外观与设置
设置依次为：启用模组作品 Dashboard → 卡片目录 → 微信读书 → 示例 → 添加卡片模块 → 添加图片橱窗 → 已有模块 → 笔记代码块生成。
按用途展开“添加卡片模块”或“添加图片橱窗”，填写模块名称、选择作品类型（普通模块）和比例，可选一个或多个 Dashboard，也可新建分类并放入，然后点击保存并收起。不选择分类也能保存。两个入口的类型固定、草稿独立；高级样式仅选择整幅封面或简约，不转换存储类型。保存后点击左侧紫色叠卡图标，在 Magical Cards 标签页体验。设置中的预览仅能浏览和滑动，不会翻面或打开描述编辑。
“高级设置”依次包含：卡片样式 → 显示方式 → 卡片材质 → 动效布局 → 仅显示三张卡片。弯曲画廊才显示方向。新模块预设为 整幅封面、填满裁切、纸感、2:3、倾斜轮播、关闭仅三张；阅读／影视示例和已有模块保留原外观。三卡选项分别作用于各模块，仍可浏览全部图片。
普通卡片批量导入与资料
阅读、影视和自定义普通模块的菜单提供 批量导入图片／SVG。一次选择多张，每张生成独立卡片与作品笔记，名称取文件名，摘要留空。支持 PNG、JPEG、WebP、GIF 和安全 SVG；每图最多 10 MB，SVG 最多 2 MB。
部分失败时，仅重试未完成图片，成功卡片不会重复创建，也不会覆盖后来编辑的名称、摘要或封面。切换分类和删除模块前需完成导入或明确放弃重试；放弃保留已写入的笔记和图片。文件重试队列仅在当前共享卡片库保持打开期间存在，完整退出后重新选图属于新导入。
作品笔记默认只展开 名称、摘要，其他属性在 更多信息。观看日期、观看状态不再提供控件，旧值保留。每张影视类型卡片都能单独修改“导演”字段名称，例如“开发商”；空标签恢复为“导演”。
比例新增 32:15 宽幅横图，适合约 2.13:1 的横幅；2:3 竖向封面适用于竖版图片。选择“完整显示”保留全部图像，“填满裁切”贴满卡片并可能裁切边缘。
图片橱窗
橱窗适合只展示图片的收藏。在设置中展开独立的添加图片橱窗，填写名称、选择比例并保存。此入口始终创建橱窗，已有作品模块不转换为橱窗。保存失败时保留草稿与已经创建的橱窗笔记，重试不会重复建笔记。
- 点击橱窗的添加图片按钮批量选择图片，也可拖入图片。不会自动扫描文件夹；支持 PNG、JPEG、WebP、GIF 和安全 SVG，每张最大 10 MB，SVG 最大 2 MB。
- 每个橱窗独用一个文件夹与一篇
橱窗.md，导入图片复制到该文件夹。打开笔记即可看到全部图片、可选名称与描述。图片名称可以留空。 - 高级设置可关闭翻面，或把名称放在正面、背面、不显示。默认开启翻面、名称放在背面，正面聚焦图片。正面名称模式的背面仅显示描述；不显示名称会保留已填写文字。
- 背面描述为最多 400 字纯文本，自动保存；输入法输入期间等待确认，冲突或失败保留草稿并提供重试。关闭翻面后仍可通过“编辑当前图片”或共享笔记修改资料。
- 删除单张卡片仅移除其笔记区块，图片文件保留。图片顺序也保存在共享笔记中；修改目标字段和排序保留其他区块及未知属性。请保留卡片 ID 和管理标记。笔记缺失或标记损坏时提示修复，不会重建空笔记。
嵌入笔记
展开设置中的「笔记代码块生成」，选择一个或多个已有模块，然后生成并复制代码，粘贴进笔记即可。也可在笔记内执行「插入卡片模块」命令，选择模块后直接插入代码块。每次生成新的代码块 ID 和模块实例 ID；引用原作品，默认继承集合设置。
同一集合可以出现在多篇笔记中。嵌入中的模块顺序只影响该代码块；排序原子更新 modules 数组，保留其余正文。重复 ID、源码冲突或未保存的原生编辑会阻止覆盖并保留草稿。复制代码到同一笔记时，请重新生成 ID。
collection 引用 book、film 或已有自定义集合的稳定 ID。模块可增加 layout：cylinder、coverflow-carousel、album-rail、scroll-bend 或 skewed-carousel；弯曲画廊可增加 orientation: vertical。这些覆盖只影响该处展示。省略时继承集合设置。
常见问题与数据
开启三卡后，其他作品会消失吗？
不会。同屏最多显示当前卡和两张邻卡；仍可浏览全部作品，作品数量不会改变。
封面为什么留边？
「完整显示」保留图片全部内容，比例不同时可能留边；「填满裁切」贴满卡片，会裁切部分图片。原图自身的白边属于图片内容，插件会保留它。
数据保存在哪里？
作品是卡片目录中的普通 Markdown 笔记；外观与模块顺序保存在 _数据/卡片配置.md。插件本地配置保存目录、首次体验状态、模组作品 Dashboard 开关、更新说明已读状态及必要恢复信息。切换目录不会重新导入示例或迁移原作品。
修改外观后标签页黑屏怎么办？
先等待保存完成，再退出并重新启动 Obsidian，打开原笔记库。外观已保存，作品和图片保留；修改现有模块外观时也会显示这条恢复提示。
是否联网或读取剪贴板？
微信读书导入是可选功能：只有主动点击「读取书架」时，才向微信读书官方网关 https://i.weread.qq.com/api/agent/gateway 请求当前书架，并发送保存在 SecretStorage 中的授权密钥；不自动同步，也不上传笔记内容。内置示例离线可用；远程封面 URL（包括导入书目的封面）会向相应图片服务器加载资源。插件不收集遥测。「复制」只在用户点击后写入生成的代码；编辑标题时，主动粘贴仅读取该次粘贴的纯文本，不在后台读取剪贴板。关联笔记选择器搜索笔记库中的笔记路径，不向外发送笔记内容。
可以在手机上使用吗？
支持 iOS／iPadOS 和 Android 版 Obsidian。能正常运行 Android 版 Obsidian 的鸿蒙设备使用同一安装包；鸿蒙原生版或兼容容器取决于宿主的插件能力，尚未验证。Obsidian 当前官方手机客户端下载入口为 iOS 和 Android。
手机上在底部菜单选择「打开 Magical Cards」，或在命令面板执行「Magical Cards：打开卡片视图」。模块菜单可批量选择图片或 SVG，SVG 可从系统文件选择器导入。卡片下方的「上一张／下一张」用于翻页；按住 400ms 后每 160ms 切换一张，松手停止。单指滑动留给 Obsidian 侧栏和页面滚动，双指仍可缩放；横向、竖向画廊都使用按钮翻页。点击邻卡先居中，点击当前卡右上角透明区域翻面，其他位置打开笔记。翻面后在原模块内放大背面并暂停翻页，返回正面保留当前位置。三张卡会按模块宽度和可视高度缩放，不改变已保存的比例和外观。Dashboard 标签左右滑动查看，在分类菜单用「向前移动／向后移动」排序。模块仍可拖动标题手柄调整位置。
手机设置和卡片资料与桌面版共用 Markdown 文件。请先让所使用的笔记同步工具完整同步笔记及附件，再打开卡片。手机浏览器模拟检查不等同于实机验收；iOS、Android、鸿蒙和 Windows 尚未实机验证。插件界面目前为中文。
原 barry-cards 代码块、作品 ID、bw_* 属性、视图和恢复草稿继续兼容；旧目录及未知配置字段保留。
先备份原 .obsidian/plugins/barry-cards/ 与卡片目录，再停用旧插件，等待未保存修改写入完成。将三个新文件安装到 magical-cards，把原 data.json 和恢复 JSON 一并保留到新目录，最后按原启用状态启用新插件。不要同时启用两个独立插件。
新版保留现有作品、编辑和排序草稿。最终停用时保存失败的草稿会写入插件目录的恢复 JSON，并提示位置。
0.9.1 修复
修复删除模块时确认框背景透明、文字与设置页面重叠的问题；适配独立设置窗口、明暗主题及窄面板，避免其他插件旧版同名样式的影响。
0.9.0 更新
- 微信读书书目导入：在设置中授权、读取书架、搜索并勾选电子书或有声书，导入内置阅读或普通书籍模块。同模块去重，跨模块可留独立副本，已有内容保持不变。
- 独立模组作品 Dashboard：点击搜索左侧的传送图标，进入紧凑的统计、作品横幅与封面墙；支持搜索、状态筛选和临时排序，返回时恢复来源位置。
- 书籍模块：新建普通模块时可选影视或书籍，默认保留影视类型；已有模块不转换类型。
完整版本记录见 Releases。
使用许可与源码
从 0.9.0 起，Magical Cards 的作者代码采用专有许可：个人和企业可以免费正常使用，允许个人备份与私人修改；未经作者许可，不得二次发布、改名分发或售卖插件及该版本起的源码。完整工程、测试与构建流程在私有源码仓库维护，本公开仓库用于安装、更新、文档和问题反馈。
已经以 MIT 发布的旧版本仍适用其原有 MIT 许可，新许可不撤销旧版已授予的权利。第三方组件继续适用各自许可证，见 THIRD_PARTY.md。第三方封面及含封面的预览图归各自权利人，不受作者代码许可授权；请保留封面来源与版权。
示例笔记库 仅包含三本书、三部影视及独立示例 ID；安装三个插件文件后用 Obsidian 打开即可。其卡片目录为「示例」。说明页模板 用于首次体验。