自定义类组件
自定义类组件用于把插件预设之外的内容放到主页中。目前包含“文档编辑器”“文字内容”和“网页浏览器”三个组件，均可直接使用。
需要直接编辑思源文档时选择“文档编辑器”；需要展示说明、清单或欢迎语时选择“文字内容”；需要嵌入在线页面或局域网页面时选择“网页浏览器”。
当前可用组件
| 组件 | 内容来源 | 适合场景 |
|---|---|---|
| 文档编辑器 | 思源中的文档块 | 固定编辑某篇文档，或浏览根文档 |
| 文字内容 | 手动填写的 Markdown | 主页说明、导航提示、清单、公告 |
| 网页浏览器 | HTTP 或 HTTPS 网页 | 在线工具、监控页面、局域网服务 |
添加组件后，打开“组件内容 → 自定义”，再从“选择组件”中选择需要的类型。三种组件保存的配置彼此独立；切换类型后，应重新检查当前输入内容再点击“确定”。
一、文档编辑器
文档编辑器会在主页组件中创建一个思源 Protyle 编辑器。它不是只读预览：在组件内修改正文、插入块或调整格式，都会直接作用于原文档。
固定显示一篇文档
- 打开要放到主页中的思源文档。
- 从文档或块的菜单中复制它的块 ID。
- 打开主页组件的内容设置。
- 进入“自定义 → 文档编辑器”。
- 关闭“随机漫游文档”。
- 将 ID 粘贴到“文档块 ID”。
- 点击“确定”并等待编辑器加载。
思源 ID 通常类似 20250310094404-1yla4zz。组件只接受有效的思源节点 ID；填写文档名称、路径或思源内部跳转链接都不能代替 ID。
文档编辑器中的改动会保存到原文档。若只想在主页中快速打开文档而不直接编辑，可以改用“最近文档”“收藏文档”“子文档”等笔记数据组件。
随机漫游文档
开启“随机漫游文档”后，“文档块 ID”输入框会隐藏，组件在加载时自动取得一个候选根文档并打开。
当前候选范围有两个特点：
- 只读取已经打开的笔记本；
- 以笔记本根目录下的文档为候选，深层子文档不会直接进入这次候选列表。
因此，如果希望某篇文档参与漫游，可以把它放在笔记本根目录；如果希望始终打开同一篇文档，应关闭随机漫游并填写固定 ID。
布局与使用建议
- 编辑器需要同时容纳工具栏和正文，建议使用较宽、较高的组件区域；
- 首次加载 Protyle 会比普通文字组件稍慢；
- 不建议在一个主页中同时放置过多文档编辑器，以免增加初始化开销；
- 切换文档 ID 后如果仍显示旧内容，可重新打开主页或点击组件刷新按钮；
- 删除主页组件只会移除组件本身，不会删除被编辑的思源文档。
二、文字内容
文字内容组件把输入的 Markdown 转换为 HTML 后显示，适合制作主页欢迎语、使用说明、快捷清单、值班提醒或项目概览。
创建文字卡片
- 打开“组件内容 → 自定义 → 文字内容”。
- 在“自定义文字内容”中输入 Markdown。
- 点击“确定”查看渲染结果。
- 根据内容长度调整组件的宽度和高度。
可以使用标题、段落、有序列表、无序列表、粗体、斜体、引用、行内代码、代码块、表格、链接、图片和分隔线。内容超过组件高度后，可以在组件内部滚动阅读。
自定义文字保存在组件配置中，不会自动同步到某篇思源文档。需要长期维护、频繁编辑或参与搜索的内容，建议使用“文档编辑器”；只在主页展示的简短说明，则更适合“文字内容”。
排版建议
- 简短欢迎语可以使用横向卡片；
- 清单、说明和表格应增加组件高度；
- 图片会按组件宽度等比缩放，仍建议使用体积较小的图片；
- 长代码和宽表格可能需要横向空间，不要把组件设置得过窄；
- 链接会按可点击文本显示，发布前应确认目标地址可信且有效。
三、网页浏览器
网页浏览器会把指定地址嵌入主页。它适合展示可以被嵌入的在线工具、个人服务面板、局域网应用或公开网页。
填写网页地址
- 打开“组件内容 → 自定义 → 网页浏览器”。
- 在“网页地址”中填写目标地址。
- 点击“确定”并等待页面加载。
- 根据网页本身的布局调整组件尺寸。
地址支持以下写法：
| 输入形式 | 处理方式 | 示例 |
|---|---|---|
| 完整公网地址 | 按原地址打开 | https://example.com/page |
| 不带协议的公网域名 | 自动补充 https:// | example.com |
localhost、局域网 IP 或 .local 地址 | 自动补充 http:// | 192.168.1.20:8080 |
只输入普通文字、文件路径或不受支持的协议时，组件会认为地址无效，并显示“请在设置中配置有效的网页地址”。
不同运行环境的差异
| 运行环境 | 加载方式 | 使用体验 |
|---|---|---|
| 桌面客户端 | Electron Webview | 兼容性相对最好，适合需要交互的网页 |
| 网页端或 Docker | Iframe | 会提供外部打开入口，部分网站可能拒绝嵌入 |
| 移动端 | 默认先显示兼容提示 | 建议外部打开，也可以手动尝试内嵌预览 |
网页端、Docker 和移动端使用 Iframe 时，目标网站可以通过安全策略禁止被其他页面嵌入。遇到空白、超时或拒绝连接，不一定是插件故障；先尝试“新标签页打开”，再确认目标网站是否允许 Iframe。
安全与隐私
网页组件会实际加载目标站点。不要随意嵌入来源不明的登录页、脚本页面或要求输入敏感信息的网站；局域网服务也应确认访问权限和账号安全。
- 优先使用 HTTPS 公网页面；
- 登录状态、Cookie 和站点权限由当前运行环境决定；
- 网页是否允许摄像头、麦克风、通知或下载，取决于思源客户端与目标站点；
- 不要把只能本机访问的
localhost地址误当成其他设备也能访问的地址； - 在移动端访问局域网地址前，确认手机与服务端处于可连通的网络中。
常见问题
文档编辑器一片空白
- 检查文档块 ID 是否完整。
- 确认对应文档没有被删除。
- 确认当前笔记本已打开。
- 重新保存组件或刷新主页。
Markdown 没有按预期显示
- 检查标题、列表和代码块前后是否留有空行；
- 检查围栏代码块的反引号是否成对；
- 图片地址必须能够被当前思源环境访问；
- 内容过长时向下滚动，排除只是被组件高度裁切。
网页可以单独打开，但组件内是空白
这通常说明目标网站禁止 Webview 或 Iframe 嵌入。桌面客户端可以先确认地址正确；网页端、Docker 和移动端则优先使用组件提供的“新标签页打开”。
选择建议
| 你的目标 | 推荐组件 |
|---|---|
| 在主页直接维护一篇思源文档 | 文档编辑器的固定文档模式 |
| 打开主页时浏览一个根文档 | 文档编辑器的随机漫游模式 |
| 展示简短说明、清单或欢迎语 | 文字内容 |
| 嵌入在线工具或局域网页面 | 网页浏览器 |
自定义组件的价值在于把最常用的内容直接放到主页，但主页仍应保持轻量。优先放置每天都会使用的文档、说明或网页，低频内容保留为普通文档或书签即可。