Jamdesk Documentation logo

自定义 CSS 和 JavaScript 示例

使用 CSS 和 JavaScript 自定义页眉标志与配色,并添加悬浮式 Ask AI 按钮,兼容 Jamdesk 更新。

本页将在一个名为 Harbor 的演示网站上构建示例。页眉将使用 Harbor 的标志和配色,并添加两个链接;右下角还会显示一个悬浮的 Ask AI 按钮。你可以直接复制这些文件,再换成自己的标志和配色。

屏幕截图显示的是英文界面。

文档网站,深蓝色页眉下方有一条橙色线,带有胶囊形的 Search 和 Ask AI 按钮,右下角有一个橙色 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 中:

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 变量控制。在页眉内部设置这些变量,即可只更改页眉样式:

style.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 按钮

添加悬浮的 Ask AI 按钮

脚本会向页面添加一个普通的 <button>。点击它会发送 Ctrl+I,也就是打开或关闭聊天面板的键盘快捷键。页眉中的 Ask AI 按钮执行相同操作。

script.js
(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:

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。聊天面板打开时会遮住屏幕的大部分区域,因此按钮会隐藏,直到聊天面板关闭:

手机宽度下的文档网站视图,带有深蓝色页眉,右下角有橙色 Ask AI 按钮

要使用此按钮,必须启用 AI 聊天。如果在 docs.json 中将 chat.enabled 设为 false,点击按钮不会有任何效果。这种情况下请不要添加该按钮。

Crisp 或 Intercom 等支持小组件可能也会显示在右下角。你可以在 #ask-ai-fab 上使用 left: 24px 而不是 right,让它们彼此错开;也可以增大 bottom 的值,将按钮移到小组件上方。

每次页面更改后运行代码

访客首次打开网站时,脚本会运行一次。在文档中点击链接时,页面内容会在不重新加载的情况下切换,脚本不会再次运行。Ask AI 按钮不受影响,因为它附加在 <body> 上,而 <body> 会保持不变。

如果代码需要读取或更改页面内容,就必须知道页面何时发生变化。下面的代码片段会监视主列,并检查 URL 是否已更改。将它放在同一个 script.js 文件中,位于按钮代码下方:

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)和深色模式下检查效果,不要只在桌面端检查。页眉颜色和固定定位的按钮通常会在这些情况下出现问题。

接下来做什么?

自定义 CSS

CSS 文件的存放位置及其加载方式

自定义 JavaScript

脚本加载方式、文件顺序和限制