自定义 CSS 和 JavaScript 示例
使用 CSS 和 JavaScript 自定义页眉标志与配色,并添加悬浮式 Ask AI 按钮,兼容 Jamdesk 更新。
本页将在一个名为 Harbor 的演示网站上构建示例。页眉将使用 Harbor 的标志和配色,并添加两个链接;右下角还会显示一个悬浮的 Ask AI 按钮。你可以直接复制这些文件,再换成自己的标志和配色。
屏幕截图显示的是英文界面。

此页眉有哪些不同之处
开箱即用时,Jam 页眉与页面融为一体。浅色模式下,页眉是透明的,能看到后面的柔和渐变。深色模式下,页眉则与其他部分一样呈近乎黑色。按钮的圆角略微弯曲。Harbor 版本做了四处调整:
- 深色模式下,页眉也会显示为深蓝色栏。
- 底边有一条细橙线。
- 搜索框、Ask AI 和 Book a demo 都采用完全圆润的胶囊形样式。
- 使用 Harbor 的白色标志替换默认标志。
这些改动只涉及 CSS 和一个标志文件,不会更改 Jamdesk 的页眉本身。搜索、Ask AI、主题切换和移动菜单仍按原样工作。
示例会在项目中使用以下文件:
harbor-docs/
├── docs.json ← logo, header links and brand colors
├── style.css ← header and button styles
├── script.js ← creates the Ask AI button
└── images/
└── harbor-logo.svg ← white logo for the navy header
从 docs.json 开始
第一部分不需要编写代码。标志、配色、页眉链接和 Book a demo 按钮都配置在 docs.json 中:
{
"logo": {
"light": "/images/harbor-logo.svg",
"dark": "/images/harbor-logo.svg"
},
"colors": {
"primary": "#C2410C",
"light": "#D9480F",
"dark": "#9A3412"
},
"navbar": {
"links": [
{ "label": "Blog", "href": "https://example.com/blog" },
{ "label": "Status", "href": "https://example.com/status" }
],
"primary": {
"type": "button",
"label": "Book a demo",
"href": "https://example.com/demo"
}
}
}标志是白色的。页眉始终为深蓝色。light 和 dark 使用同一个文件。
Jamdesk 会将 primary 配色用于 Book a demo 按钮、当前侧边栏项目和链接。深色模式下则改用 light 配色。请确保颜色足够深,让按钮上的白色文字仍清晰易读。所有 navbar 选项请参阅导航链接。
在将标志放在页眉中的主题(Jam、Nebula、Halo 和 Dusk)里,屏幕宽度为平板或桌面尺寸时,navbar 链接会显示在页眉中。在手机上,这些链接会移入菜单,下面的页眉样式不会应用于菜单。Pulsar 会将标志放在侧边栏中,桌面端没有页眉栏,因此下面的页眉样式不会在 Pulsar 中显示。
设置页眉样式
页眉的文字、边框、搜索框和圆角由 CSS 变量控制。在页眉内部设置这些变量,即可只更改页眉样式:
/* header[data-has-tabs] matches the site header only.
A plain `header` selector would also match the title
block at the top of every page. */
header[data-has-tabs] {
--header-top: #0f1d3a;
--header-bottom: #1b2f5b;
--header-stripe: #f97316;
--color-text-primary: #ffffff;
--color-text-secondary: #cbd5e1;
--color-text-tertiary: #cbd5e1;
--color-text-muted: #94a3b8;
--color-bg-primary: #0f1d3a;
--color-bg-secondary: rgba(255, 255, 255, 0.08);
--color-bg-hover: rgba(255, 255, 255, 0.16);
--color-border: rgba(255, 255, 255, 0.16);
/* Rounds the search box, Ask AI and buttons into pills */
--radius-md: 999px;
--radius-lg: 999px;
}
html.dark header[data-has-tabs] {
--header-top: #0a1328;
--header-bottom: #13234a;
--color-bg-primary: #0a1328;
}
/* Some themes keep the header background transparent on
purpose, so paint the color on a layer behind it. */
header[data-has-tabs]::before {
content: "";
position: absolute;
inset: 0 -24px; /* reach past the 16-24px page gutter */
z-index: -1;
background: linear-gradient(
90deg, var(--header-top), var(--header-bottom)
);
border-bottom: 3px solid var(--header-stripe);
}
/* The sparkle icon uses the accent color, which is hard to
see on navy, so give it the stripe color instead */
header[data-has-tabs] .fa-sparkles {
color: #fdba74;
}深蓝色背景应用在 ::before 伪元素图层上,因为 Jam 主题会通过 !important 将页眉的 background 设置为 none。直接给页眉设置普通的 background 规则会被覆盖。该图层位于页眉内容后方,可在所有主题中正常工作。
将 --radius-md 和 --radius-lg 设为 999px,即可把页眉按钮变成胶囊形。此改动仅作用于 header[data-has-tabs]。页面上的卡片和代码块仍保持原有圆角。
页眉中的 Ask AI 图标使用你的强调色,但该颜色在深蓝背景上不易看清。最后一条规则会将图标颜色设为浅橙色。
深色模式下,Jamdesk 会给 <html> 添加 dark 类。html.dark 代码块会让深色模式下的深蓝色稍暗一些:

添加悬浮的 Ask AI 按钮
脚本会向页面添加一个普通的 <button>。点击它会发送 Ctrl+I,也就是打开或关闭聊天面板的键盘快捷键。页眉中的 Ask AI 按钮执行相同操作。
(function () {
if (document.getElementById('ask-ai-fab')) return;
var button = document.createElement('button');
button.id = 'ask-ai-fab';
button.type = 'button';
// Jamdesk loads Font Awesome, so its icons are available here
var icon = document.createElement('i');
icon.className = 'fa-solid fa-sparkles';
icon.setAttribute('aria-hidden', 'true');
button.append(icon, ' Ask AI');
button.addEventListener('click', function () {
// Same as pressing Ctrl+I / Cmd+I: toggles the chat panel
var shortcut = { key: 'i', ctrlKey: true, bubbles: true };
document.dispatchEvent(new KeyboardEvent('keydown', shortcut));
});
document.body.appendChild(button);
})();然后将按钮样式添加到 style.css:
#ask-ai-fab {
position: fixed;
right: 24px;
bottom: 24px;
z-index: 40; /* below the header, search and mobile menu */
display: inline-flex;
align-items: center;
gap: 8px;
padding: 12px 18px;
border: 0;
border-radius: 999px;
background: #c2410c;
color: #fff;
font: inherit;
font-weight: 600;
box-shadow: 0 6px 20px rgba(15, 29, 58, 0.25);
cursor: pointer;
}
#ask-ai-fab:hover {
background: #9a3412;
}
#ask-ai-fab:focus-visible {
outline: 2px solid #f97316;
outline-offset: 2px;
}
/* Hide the button while the chat panel is open. On mobile
the closed panel stays in the page with data-open="false",
so exclude that case. */
body:has([data-chat-panel]:not([data-open="false"])) #ask-ai-fab {
display: none;
}
@media (max-width: 767px) {
#ask-ai-fab {
right: 16px;
bottom: 16px;
}
}在手机上,按钮距离屏幕边缘 16px。聊天面板打开时会遮住屏幕的大部分区域,因此按钮会隐藏,直到聊天面板关闭:

要使用此按钮,必须启用 AI 聊天。如果在 docs.json 中将 chat.enabled 设为 false,点击按钮不会有任何效果。这种情况下请不要添加该按钮。
Crisp 或 Intercom 等支持小组件可能也会显示在右下角。你可以在 #ask-ai-fab 上使用 left: 24px 而不是 right,让它们彼此错开;也可以增大 bottom 的值,将按钮移到小组件上方。
每次页面更改后运行代码
访客首次打开网站时,脚本会运行一次。在文档中点击链接时,页面内容会在不重新加载的情况下切换,脚本不会再次运行。Ask AI 按钮不受影响,因为它附加在 <body> 上,而 <body> 会保持不变。
如果代码需要读取或更改页面内容,就必须知道页面何时发生变化。下面的代码片段会监视主列,并检查 URL 是否已更改。将它放在同一个 script.js 文件中,位于按钮代码下方:
(function () {
var lastPath = location.pathname;
var main = document.getElementById('main-content') || document.body;
function onPageChange() {
// Your per-page code goes here
console.log('Now on', location.pathname);
}
new MutationObserver(function () {
if (location.pathname === lastPath) return;
lastPath = location.pathname;
onPageChange();
}).observe(main, { childList: true, subtree: true });
})();无论访客是点击侧边栏链接、使用搜索,还是按下后退按钮,onPageChange 都会在每个新页面上运行一次。
可用的选择器
Jamdesk 的类名来自 Tailwind,可能会在任何版本更新中发生变化。按钮标签也可能改变,多语言网站还会翻译这些标签。请改用以下选择器:
| 选择器 | 匹配内容 |
|---|---|
html.dark | 深色模式下的页面 |
body[data-theme="jam"] | 当前主题,按名称匹配(jam、nebula、pulsar、halo、dusk) |
header[data-has-tabs] | 网站页眉 |
#main-content | 主列,包含页面内容和目录 |
#content-scroll-container | 页面内容列 |
article .prose | 当前页面的正文 |
[data-chat-panel] | AI 聊天面板 |
[data-theme-toggle] | 浅色/深色/系统模式切换控件 |
body[data-jd-ready="true"] | 首个页面加载完成后设置 |
不要将 Jamdesk 自身的元素移到其他容器中,也不要用脚本隐藏这些元素。访客浏览页面时,Jamdesk 会重新绘制部分页面内容。移动元素可能导致它跳回原处或破坏导航。请像 Ask AI 按钮那样,将自定义元素添加到 Jamdesk 元素旁边。
测试更改
jamdesk dev 会显示 CSS 效果,但不会运行自定义 JavaScript。AI 聊天只在已发布的网站上可用。你可以在预览页面的浏览器控制台中粘贴脚本,在本地试用。按钮会显示出来,但发布前无法打开聊天面板。
请在手机屏幕尺寸(宽 375px)和深色模式下检查效果,不要只在桌面端检查。页眉颜色和固定定位的按钮通常会在这些情况下出现问题。
接下来做什么?
