十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Etherpad 嵌入参数(Embed Parameters)完全指南:用 iframe 与 URL 参数深度定制嵌入式协作编辑器

Etherpad 嵌入参数(Embed Parameters)完全指南:用 iframe 与 URL 参数深度定制嵌入式协作编辑器 Etherpad 嵌入参数Embed Parameters完全指南用 iframe 与 URL 参数深度定制嵌入式协作编辑器【免费下载链接】etherpadEtherpad: A modern really-real-time collaborative document editor.项目地址: https://gitcode.com/gh_mirrors/et/etherpadEtherpad 提供了基于 iframe 的一键嵌入能力任何网页都可以通过一段 HTML 片段把实时协作编辑器嵌入进来并通过 URL 查询参数精细控制嵌入形态。本文以官方文档 doc/api/embed_parameters.md 为主体结合仓库源码中参数的解析链路src/static/js/pad.ts、src/node/utils/Settings.ts与端到端测试src/tests/frontend-new/specs/embed_value.spec.ts逐一讲解全部嵌入参数的语义、默认值、编码规则与底层实现读完即可按需拼出可复制的 iframe 嵌入代码。快速上手一个 iframe 嵌入示例把下面这段代码粘贴到任意网页中即可嵌入一个 Etherpad 文档。示例同时演示了参数组合隐藏聊天栏与行号、并把光标自动定位到第 4 行开头iframe srchttp://pad.test.de/p/PAD_NAME#L4?showChatfalseshowLineNumbersfalse width600 height400/iframe关键结构说明http://pad.test.de/p/PAD_NAME是 pad 的标准 URL/p/pad名称路径#L4是hash 片段Fragment不是查询参数用于把编辑器滚动并聚焦到第 4 行光标落在该行行首?showChatfalseshowLineNumbersfalse是查询参数分隔多个参数false/true字符串会被解析为布尔开关。仓库自带的“分享/嵌入”对话框也会生成等价代码。在 pad 页面工具栏点击分享按钮src/static/js/pad_editbar.ts 中的setEmbedLinks()会生成如下默认嵌入代码已带showControlstrueshowChattrueshowLineNumberstrueuseMonospaceFontfalse四个显式参数iframe nameembed_readwrite srchttp://pad.test.de/p/PAD_NAME?showControlstrueshowChattrueshowLineNumberstrueuseMonospaceFontfalse width100% height600 frameborder0/iframe勾选“只读”选项后src会切换为只读域URL 路径中带有r.前缀的只读 IDiframe 的name变为embed_readonly。该行为由端到端测试 src/tests/frontend-new/specs/embed_value.spec.ts 断言验证包括参数拼写、iframe 尺寸宽 100%、高 600以及只读链接的形态。参数总览参数类型默认值作用showLineNumbersBooleantrue是否显示行号栏showControlsBooleantrue是否显示编辑工具栏showChatBooleantrue是否显示聊天useMonospaceFontBooleanfalse是否使用等宽字体userNameStringunnamed预置作者昵称userColorStringCSS hex 颜色由 pad 服务端随机分配预置作者颜色noColorsBooleanfalse关闭作者着色alwaysShowChatBooleanfalse聊天窗口常驻显示langStringen界面语言rtlBoolean见下文说明文本从右到左显示#LInt0未提供则不定位定位到指定行hash 值非查询参数其中布尔参数实际只会匹配特定字符串值这与底层getParameters解析表有关详见后文“参数如何被解析”。参数逐项详解showLineNumbersBoolean默认true控制编辑器左侧的行号栏是否显示。传入false时隐藏行号例如?showLineNumbersfalse。从解析表看src/static/js/pad.ts该参数仅在值恰好等于false时触发回调将内部标志settings.LineNumbersDisabled置为true因此显式传true是空操作行号保持默认显示。前端测试 src/tests/frontend-new/specs/url_view_options.spec.ts 专门覆盖了“showLineNumbersfalse首屏隐藏行号槽”与“showLineNumberstrue不回归”两个场景。showControlsBoolean默认true控制编辑工具栏editbar是否显示。传入true时强制显示工具栏src/static/js/pad.ts 中通过把#editbar的 CSSdisplay设为flex实现。该参数只响应显式的true。与它配合使用的是参数表中未在旧文档列出、但源码已实现并附注释的showMenuRightsrc/static/js/pad.ts显式传false会隐藏右侧工具栏导入/导出、时间滑条、设置、嵌入、用户等按钮适合嵌入只读 pad 时去掉多余“chrome”对应 issue #5182。showChatBoolean默认true控制聊天模块是否显示。与其它布尔参数不同它接受任意值showChatfalse时隐藏聊天并隐藏聊天图标settings.hideChat true; chat.hide(); $(#chaticon).hide()其它值则恢复显示src/static/js/pad.ts。useMonospaceFontBoolean默认false嵌入时是否让编辑器使用等宽字体。传入true时设置全局等宽字体标志src/static/js/pad.ts。默认值为false即使用默认字体渲染。userNameString默认unnamed预置嵌入访客的显示昵称。由于 URL 中不能直接出现空格空格必须编码为%20?userNameEtherpad%20User参数值会被写入settings.globalUserName与clientVars.userNamesrc/static/js/pad.ts随后在握手完成后通过notifyChangeName()同步给服务端并更新用户列表 UIsrc/static/js/pad.ts。值得注意的实现细节解析表对userName与userColor有哨兵值防护。旧版settings.json曾用布尔false表示“未强制设置”这会被字符串化后误当作字面量用户名/颜色发给服务端issue #7686。当前实现会在回调入口拒绝空值与字符串falsesrc/static/js/pad.ts因此?userNamefalse这类写法也是空操作。userColorStringCSS hex 颜色默认由 pad 服务端随机分配预置嵌入访客的作者颜色。CSS hex 颜色中的#在 URL 中必须编码为%23?userColor%23ff9900即等价于颜色值#ff9900。参数值写入settings.globalUserColor与clientVars.userColor在握手完成后通过notifyChangeColor()通知服务端src/static/js/pad.ts并受colorutils.isCssHex()校验非合法 hex 值不会生效。同userName一样空值或false会被拒绝。noColorsBoolean默认false关闭多作者的彩色高亮显示。传入true时隐藏“清除作者信息”按钮并设置settings.noColors truesrc/static/js/pad.ts。在编辑器侧src/static/js/pad_editor.ts 会根据settings.noColors决定是否关闭showsauthorcolors作者着色属性。alwaysShowChatBoolean默认false让聊天窗口常驻钉在屏幕上不自动收起。传入true时调用chat.stickToScreen()src/static/js/pad.ts。注意回调内部有保护条件仅当聊天未被showChatfalse隐藏时才执行钉屏。langString默认en切换界面语言。Etherpad 支持 60 语言语言目录见 src/locales例如ar.json、zh-hans.json、ja.json等。示例?langar将界面翻译为阿拉伯语。实现上调用html10n.localize([val, en])完成本地化并把选择写入以 cookie 前缀命名的languagecookiesrc/static/js/pad.ts语言菜单同时会同步为当前值src/static/js/pad_editor.ts。rtlBoolean默认值见说明以从右到左RTL方向显示 pad 文本适用于阿拉伯语、希伯来语等书写方向。需要说明默认值差异官方文档记载默认值为true但从当前仓库实现看实际默认取决于界面语言的方向——src/static/js/pad_editor.ts 中rtlIsTrue的回退默认是(rtl html10n.getDirection())即跟随当前界面语言而 settings.json.template 中服务端padOptions.rtl的默认值是false。此外解析表src/static/js/pad.ts会把?rtltrue/?rtlfalse映射为settings.rtlIsTrue并标记rtlIsExplicit来自 URL 的显式设置显式参数优先于上述默认逻辑。#LInt默认 0特殊hash 值而非查询参数将编辑器滚动到指定行并把光标放在该行行首。因为它是 URL 的hash 片段必须放在?查询参数之前/p/PAD_NAME#L4?showChatfalseshowLineNumbersfalsehash 与查询参数的顺序不能颠倒#L4在前、?参数在后。定位由 src/static/js/pad_editor.ts 的getHashedLineNumber()解析——读取location.hash校验格式为L正整数非法值返回null即不定位等价于“默认 0 / 不聚焦”。定位实现还包含一个布局稳定窗口src/static/js/pad_editor.tsfocusOnLine()会周期性校正滚动位置直到目标行偏移量稳定或超过 10 秒硬上限期间一旦检测到用户交互则立即停止绝不与用户抢滚动。这样即使嵌入页面中图片、插件渲染导致目标行位置后移光标仍能准确落到第 4 行。参数如何被解析URL 优先于服务端默认值所有查询参数由 src/static/js/pad.ts 中的getParameters解析表统一驱动。每个条目包含三要素nameURL 参数名如noColorscheckVal触发条件——参数值恰好等于该值才执行回调为null时任意值均触发callback实际生效逻辑入参为 URL 中提供的字符串值。getParams()src/static/js/pad.ts按以下顺序合并两处来源读取当前 URL 的查询参数getUrlVars()即new URL(window.location.href).searchParams若 URL 提供了匹配的参数以 URL 值为准并直接执行回调跳过服务端配置否则回退到服务端下发的clientVars.padOptions即 settings.json.template 中padOptions块作为默认值。源码注释明确写道“URL query params take priority over server-enforced options”URL 查询参数优先于服务端强制的选项此举同时避免异步回调竞态例如lang被触发两次html10n.localize。因此嵌入场景中URL 参数 服务端padOptions默认值 代码内置默认值。服务端默认值settings.json 中的 padOptions嵌入参数的默认值也可以在服务端统一预置。配置文件 settings.json.template 中的padOptions块覆盖了全部嵌入参数padOptions: { noColors: false, showControls: true, showChat: true, showLineNumbers: true, useMonospaceFont: false, userName: null, userColor: null, rtl: false, alwaysShowChat: false, chatAndUsers: false, lang: null, fadeInactiveAuthorColors: true, enforceReadableAuthorColors: true }对应的 TypeScript 类型定义位于 src/node/utils/Settings.ts内置默认值在 src/node/utils/Settings.tsnoColors: false、showControls: true、showChat: true、showLineNumbers: true、useMonospaceFont: false、alwaysShowChat: false等与模板文件一致。模板中还包含两个未出现在嵌入参数文档中的扩展项fadeInactiveAuthorColors作者离线后其光标/背景色是否渐隐为白色默认trueenforceReadableAuthorColors渲染时是否将作者背景色钳制到满足 WCAG 2.1 AA 对比度4.5:1默认true只调整显示色阶、不改写作者存储颜色。此外模板里还有chatAndUsers聊天与用户列表并排显示可供预置它与alwaysShowChat一样来自服务端选项体系。嵌入最佳实践组合根据以上参数可以组合出几种常见嵌入形态1. 标准嵌入保留全部 UI等价于工具栏“嵌入”按钮生成的代码iframe srchttp://pad.test.de/p/PAD_NAME?showControlstrueshowChattrueshowLineNumberstrueuseMonospaceFontfalse width100% height600 frameborder0/iframe2. 极简阅读嵌入隐藏工具栏、聊天、行号去掉右侧菜单只读链接iframe srchttp://pad.test.de/p/r.PAD_READONLY_ID?showControlsfalseshowChatfalseshowLineNumbersfalseshowMenuRightfalse width100% height600/iframe3. 带身份与定位的协作嵌入预置昵称与颜色聚焦到第 4 行开启 RTLiframe srchttp://pad.test.de/p/PAD_NAME#L4?userNameEtherpad%20UseruserColor%23ff9900rtltrue width600 height400/iframe编码规则小结空格用%20、颜色#用%23、多参数用连接、hash 定位#L行号必须位于查询参数之前。测试与验证仓库为嵌入行为提供了端到端测试可作为验证自己配置是否正确的手段src/tests/frontend-new/specs/embed_value.spec.ts断言“分享/嵌入”对话框生成的 iframe 代码包括 URL 参数集合showControlstrueshowChattrueshowLineNumberstrueuseMonospaceFontfalse、iframe 尺寸宽 100%、高 600、name属性embed_readwrite/embed_readonly以及只读模式下 URL 含r.前缀src/tests/frontend-new/specs/url_view_options.spec.ts验证?showLineNumbersfalse首屏即隐藏行号槽、?showLineNumberstrue不产生回归。小结Etherpad 的嵌入能力全部围绕 iframe URL 展开查询参数控制界面形态与访客身份#Lhash 控制文档定位服务端padOptions提供全局默认值兜底。理解 src/static/js/pad.ts 中的getParameters解析表哪些参数只认固定值、哪些接受任意值、URL 如何覆盖服务端配置再配合 settings.json.template 的padOptions默认值即可在任意网页中按需拼装出标准、极简或带身份定位的 Etherpad 嵌入方案。【免费下载链接】etherpadEtherpad: A modern really-real-time collaborative document editor.项目地址: https://gitcode.com/gh_mirrors/et/etherpad创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表