跳到正文
ShareBooks

← 返回博客 · 登录并前往嵌入管理 · JS SDK 实测页 · 纯 iframe 实测页

使用说明

将公开书单与书籍嵌入你的网站

把公开书单、推荐卡片或单书详情放进个人博客、技术文档或读书专栏。读者无需登录或安装任何插件,打开即读。

仅公开书单可用JS SDK / 纯 iframe

一、前提条件与权限边界

  • 仅限公开书单:只有可见性为「公开」的书单(及其单书与书籍详情)可以站外嵌入。密码书单只会显示锁定提示,私密书单不会返回内容。
  • 绑定 Client ID 与域名白名单:每个嵌入客户端都会配置允许访问的域名(通过服务端 Content-Security-Policy: frame-ancestors 校验),支持精确 http(s)://host[:port](如 https://blog.example.com、http://localhost:3000)以及子域通配符(如 https://*.docs.example.com),不支持全局 * 或带路径的 URL。
  • 两种授权范围:开通客户端时可配置为「仅我的公开书单」或「全部公开书单」,超出范围的书单会返回未授权提示。

二、三步完成接入

  1. 申请并查看 Client ID:前往 登录并前往嵌入管理,点开页面上方的「?」即可查看申请方式——使用当前登录账号的邮箱发送邮件至 [email protected],附上网站名称和访问域名。开通后即可在该页面查看你的 clientId 与允许域名。
  2. 在书单或书籍页取得嵌入代码:打开任意公开书单点击「分享书单」,或进入单书详情页顶部点击「分享书籍」,在弹窗中切换「JS SDK」或「纯 iframe」即可一键复制。
  3. 替换占位符后粘贴到你的网站:为了避免拥有多个客户端时混淆,分享弹窗默认保留 <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>&sections=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&sections=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 属性可选值说明
clientIddata-client-id必填(4–64 位字母/数字/_/-)将示例中的 <clientId> 替换为你在「嵌入管理」获取的真实 ID。
sectionsdata-sectionsheader, note, intro, reviews, colophon, peers 或 alllist/item 默认 header,note;detail 默认开启前五项,peers 默认关闭。
themedata-themeauto(默认)| light | dark配色模式,auto 会跟随系统浅色/深色偏好。
bgdata-bgparchment(默认)| transparent设为 transparent 可直接透出宿主博客或文档站底色。
navdata-navblank(默认)| inlineblank 在新标签页打开原站;inline 允许在框内跳转书单与单书详情。
chromedata-chrome1(默认)| 0是否显示底部「查看原页」落款;JS SDK 挂载由宿主 DOM 承担落款,会自动传入 0。
view / limit / numbered / hideSwitchdata-view / data-limit / data-numbered / data-hide-switchlist | shelf | minimal;limit 1–100;0 | 1仅书单列表生效,用于设定初始视图、条数上限、序号与视图切换栏显示。
variantdata-variantcard(默认)| row仅书单单项目(/embed/list/<listId>/item/<itemId>)生效,切换推荐卡片或紧凑单行。

五、常见问题排查与在线实测

  • 提示「未授权」或无法在浏览器中加载:请确认已将 <clientId> 替换为真实 ID、该客户端处于「已启用」状态、书单本身为「公开」,并且当前页面的域名与端口匹配白名单。
  • 本地调试时无法显示:如需在本地预览站嵌入,申请或配置允许域名时需包含本地地址(如 localhost:3000、127.0.0.1:3080)。

想看真实运行效果与事件日志,可继续访问:JS SDK 嵌入实测页·纯 iframe 嵌入实测页·登录并前往嵌入管理