一、前提条件与权限边界
- 仅限公开书单:只有可见性为「公开」的书单(及其单书与书籍详情)可以站外嵌入。密码书单只会显示锁定提示,私密书单不会返回内容。
- 绑定 Client ID 与域名白名单:每个嵌入客户端都会配置允许访问的域名(通过服务端
Content-Security-Policy: frame-ancestors校验),支持精确http(s)://host[:port](如https://blog.example.com、http://localhost:3000)以及子域通配符(如https://*.docs.example.com),不支持全局*或带路径的 URL。 - 两种授权范围:开通客户端时可配置为「仅我的公开书单」或「全部公开书单」,超出范围的书单会返回未授权提示。
二、三步完成接入
- 申请并查看 Client ID:前往 登录并前往嵌入管理,点开页面上方的「?」即可查看申请方式——使用当前登录账号的邮箱发送邮件至 [email protected],附上网站名称和访问域名。开通后即可在该页面查看你的
clientId与允许域名。 - 在书单或书籍页取得嵌入代码:打开任意公开书单点击「分享书单」,或进入单书详情页顶部点击「分享书籍」,在弹窗中切换「JS SDK」或「纯 iframe」即可一键复制。
- 替换占位符后粘贴到你的网站:为了避免拥有多个客户端时混淆,分享弹窗默认保留
<clientId>占位符。粘贴进文章或模板前,请将其替换为你实际使用的clientId。
三、嵌入方式与形态示例
优先推荐 JS SDK:它会自动读取内容高度并消除双重滚动条,并在脚本未加载时降级为可点击的原文链接。如果博客或静态站禁止插入外链 <script>,可以使用原生 纯 iframe。
1. 书单列表(JS SDK 声明式)
对应路径 /embed/list/<listId>,支持用户在 list / shelf / minimal 间切换视图。
<div
data-wrs-embed="list"
data-client-id="<clientId>"
data-list-id="<listId>"
data-view="list"
data-sections="header,note"
data-theme="auto"
>
<a href="https://sharebooks.cc/list/%3ClistId%3E">在 WeRead Share 查看《示例书单》</a>
</div>
<script async src="https://sharebooks.cc/sdk/embed.js"></script>2. 书单单项目(JS SDK 声明式)
对应路径 /embed/list/<listId>/item/<itemId>,适合在长文中引用单本书籍推荐卡片(默认 variant=card,也可传 row)。
<div
data-wrs-embed="item"
data-client-id="<clientId>"
data-list-id="<listId>"
data-item-id="<itemId>"
data-sections="header,note"
data-theme="auto"
>
<a href="https://sharebooks.cc/list/%3ClistId%3E/book/%3CitemId%3E">在 WeRead Share 查看《示例书名》 · 示例书单</a>
</div>
<script async src="https://sharebooks.cc/sdk/embed.js"></script>3. 书籍详情(纯 iframe 方式)
对应路径 /embed/list/<listId>/book/<itemId>,适合只允许原生 HTML <iframe> 的平台,可通过 style 自行设定容器高度。
<iframe
src="https://sharebooks.cc/embed/list/%3ClistId%3E/book/%3CitemId%3E?clientId=<clientId>§ions=header,note,intro,reviews,colophon"
style="width:100%;height:680px;border:0;"
loading="lazy"
title="微信读书书籍详情 · 示例书名"
></iframe>4. 书单列表(纯 iframe 方式)
<iframe
src="https://sharebooks.cc/embed/list/%3ClistId%3E?clientId=<clientId>&view=list§ions=header,note"
style="width:100%;height:560px;border:0;"
loading="lazy"
title="微信读书分享书单 · 示例书单"
></iframe>5. 命令式 SDK(适合 React / Vue / SPA 动态挂载)
除声明式 data-wrs-embed 外,也可直接调用 window.WeReadShare.mount(target, options),并支持 onReady、onResize、onViewChange 回调。
<div id="my-booklist"></div>
<script src="https://sharebooks.cc/sdk/embed.js"></script>
<script>
const embed = window.WeReadShare.mount('#my-booklist', {
type: 'list',
clientId: '<clientId>',
listId: '<listId>',
theme: 'auto',
bg: 'transparent',
});
// 可选动态更新或卸载:embed.update({ theme: 'dark' }); embed.destroy();
</script>四、常用参数与内容裁剪
| URL 参数 | SDK 属性 | 可选值 | 说明 |
|---|---|---|---|
clientId | data-client-id | 必填(4–64 位字母/数字/_/-) | 将示例中的 <clientId> 替换为你在「嵌入管理」获取的真实 ID。 |
sections | data-sections | header, note, intro, reviews, colophon, peers 或 all | list/item 默认 header,note;detail 默认开启前五项,peers 默认关闭。 |
theme | data-theme | auto(默认)| light | dark | 配色模式,auto 会跟随系统浅色/深色偏好。 |
bg | data-bg | parchment(默认)| transparent | 设为 transparent 可直接透出宿主博客或文档站底色。 |
nav | data-nav | blank(默认)| inline | blank 在新标签页打开原站;inline 允许在框内跳转书单与单书详情。 |
chrome | data-chrome | 1(默认)| 0 | 是否显示底部「查看原页」落款;JS SDK 挂载由宿主 DOM 承担落款,会自动传入 0。 |
view / limit / numbered / hideSwitch | data-view / data-limit / data-numbered / data-hide-switch | list | shelf | minimal;limit 1–100;0 | 1 | 仅书单列表生效,用于设定初始视图、条数上限、序号与视图切换栏显示。 |
variant | data-variant | card(默认)| row | 仅书单单项目(/embed/list/<listId>/item/<itemId>)生效,切换推荐卡片或紧凑单行。 |
五、常见问题排查与在线实测
- 提示「未授权」或无法在浏览器中加载:请确认已将
<clientId>替换为真实 ID、该客户端处于「已启用」状态、书单本身为「公开」,并且当前页面的域名与端口匹配白名单。 - 本地调试时无法显示:如需在本地预览站嵌入,申请或配置允许域名时需包含本地地址(如
localhost:3000、127.0.0.1:3080)。
想看真实运行效果与事件日志,可继续访问:JS SDK 嵌入实测页·纯 iframe 嵌入实测页·登录并前往嵌入管理