Skip to content

自定义HTML模板

Jump to bottom
John Smith edited this page May 3, 2025 · 2 revisions

自定义HTML模板

v1.10新增

自定义模板可以完全自定义前端页面，如果你觉得默认的DOM结构满足不了自定义需求，可以用自定义模板。对二次开发者来说，推荐优先写自定义模板而不是改主程序代码，这样用户就不用下载多个blivechat版本了。而且自定义模板支持跨域，这意味着你可以把它部署到任何静态网站，然后用户不用下载任何文件，只需要把模板的URL填到在线版的blivechat配置里就可以用了。你甚至可以不做评论栏，而是做一些更实用的功能，比如语音播报

自定义模板能做的事：

  • 完全自定义前端，包括DOM结构、CSS
  • 复用blivechat的大部分功能，包括和B站服务器通信、解析消息、翻译弹幕等。基本上只需要自己实现渲染消息
  • 监听前端处理过的消息，可以访问默认模板不会展示的勋章等信息

模板本质上是独立的网页，主窗口会通过iframe加载模板，之后主窗口和模板窗口通过消息通信。设计成独立网页的形式有以下优点：

  • 可以跨域，二次开发者不需要部署完整的blivechat网站，只需要把模板部署到任意静态网站就能用了。用户也不需要把blivechat下载到本地，可以直接用官方的在线版网站
  • 不会限制模板使用的技术栈，可以用Vue3、React、jQuery

模板的加载流程

后端发现模板列表：

  1. blivechat前端请求模板列表时，后端会扫描data/custom_public/templates目录下的子目录，如果有template.json文件则把这个目录识别为一个模板目录
  2. template.json文件中的url字段是模板网页的URL。支持相对路径或绝对路径，相对路径是相对于模板目录的

即使不在模板列表里，用户也可以在配置里手动输入模板URL，只要房间页面能拿到模板URL就行

房间页面加载模板：

  1. 房间页面通过iframe加载模板URL
  2. 模板向父窗口发送blcTemplateConnect消息
  3. 父窗口向模板发送blcInit消息，内容包含前端版本和部分配置等信息，收到这条消息则连接完成
  4. 后续的直播间消息会发送给模板

模板开发

可以参考GitHub Discussions上发布的模板

  1. 在data/custom_public/templates目录下新建你的模板目录

  2. 准备template.json文件：

    {
  "name": "模板名",
  "version": "版本，例如1.0.0",
  "author": "作者",
  "description": "说明",
  "thumbnail": "预览图URL，例如thumbnail.jpg",
  "url": "模板URL，例如index.html"
}

    这里的模板URL和预览图URL都支持相对路径或绝对路径，相对路径是相对于模板目录的

  3. html文件中要指定no-referrer，因为B站的图床有防盗链，如果带Referer则不能显示头像

    <html>
  <head>
    <meta name="referrer" content="no-referrer">
    ...

  4. 把frontend/src/blcsdk.js文件复制到你的模板目录并导入

    <script src="./blcsdk.js"></script>

  5. 在脚本中实现你的消息处理器，继承自blcsdk.MsgHandler

    class MsgHandler extends blcsdk.MsgHandler {
  addMsg(msg) {
    ...
  }
}

    具体的接口和消息字段可以参考SDK中的文档注释。推荐实现所有接口，不然会少一些功能

  6. 模板初始化时初始化SDK

    await blcsdk.init()

  7. 设置消息处理器

    blcsdk.setMsgHandler(new MsgHandler())

发布模板

根据情况有以下的发布方式

部署到自己的网站，用户在线使用

把模板目录部署到你自己的静态网站，然后把模板URL发给用户，用户在blivechat主页的配置输入即可

部署到自己的网站，用户在本地使用

除了上面的让用户输入模板URL，你还可以把template.json文件分发给用户，让他放到本地blivechat的模板目录里。这样的好处是用户可以在模板列表里选择，而不需要记URL。注意template.json里的URL要改成你网站的绝对路径URL，不要用相对路径

打包分发给用户，用户在线使用

这是不可以的，因为浏览器禁止在线网站访问本地文件，即使是通过iframe。虽然可以本地启动一个HTTP服务器来绕过，但我不指望用户懂这个

打包分发给用户，用户在本地使用

把模板目录打包分发给用户即可

支持OBS中的自定义CSS

v1.10.1新增

OBS中的自定义CSS只会注入主窗口，所以一般不会影响模板。如果想让OBS的CSS注入模板窗口，需要满足以下条件：

  • blivechat版本 >= v1.10.1

  • 模板用的SDK版本 >= v1.0.1

  • CSS中包含字符串blc-inject-into-template，你可以把它写到注释里

    /* blc-inject-into-template */

    这个字符串只是为了区分CSS是不是OBS注入的。blivechat服务器预设CSS不需要包含这个字符串也可以注入模板

Clone this wiki locally