主题

主题用于统一设置聊天外观，包括背景、消息气泡、字体、头像和输入区。你可以直接使用已有主题，也可以复制后进行调整。

选择与编辑主题

从左侧边栏底部的「更多」进入「主题」。
选择要应用的主题，或打开自建主题进行编辑。官方主题只读，需要修改时先复制一份。
调整背景、气泡、字体、头像和输入区设置，预览后保存。

同一个主题可以被多个聊天使用，修改后会影响所有使用它的聊天。要为某个聊天单独设置外观，先创建或复制一个独立主题，再应用到该聊天。

自定义 CSS

基础设置不能满足需求时，可以在主题中添加 CSS，进一步调整消息、头像和输入区样式。此功能需要开启高级渲染。

编辑样式

在主题编辑页打开「自定义样式」，在「自定义 CSS」中填写完整 CSS 规则。不要加入 HTML、<style> 标签或 Markdown 代码围栏。
点击「CSS 助手」选择目标区域，使用「预览」查看效果，再返回主题编辑页保存，并将主题应用到聊天。
在设置中开启高级前端渲染。

编辑器提供语法高亮、缩进、撤销和重做，手机键盘弹出时还有快捷编辑栏。语法错误提示只是辅助检查，不阻止保存，也不代表浏览器一定支持所有属性。预览后仍需在真实聊天中检查长消息、键盘弹出和生成中等状态。

作用范围与覆盖规则

CSS 随主题保存，使用同一主题的聊天会共享这些规则。要只修改一个聊天，先创建或复制独立主题，再绑定到该聊天。
自定义样式在主题基础样式之后应用。
CSS 可以修改下表列出的消息、头像和 Web 输入区。设置页、菜单和系统弹窗不在作用范围内。
清空自定义 CSS 并保存即可恢复主题的基础样式。仅更改基础颜色等设置时，已有 CSS 仍可能覆盖这些设置。

公开选择器

以下清单与应用内 CSS Helper 一致，是对外支持的全部选择器。使用这些选择器搭配标准 CSS 属性，不要依赖未列出的 DOM 类、内部 CSS 变量、私有属性或子节点结构。

选择器	作用区域
`.tav-bubble`	所有消息气泡
`.tav-user-bubble`	用户气泡
`.tav-character-bubble`	角色气泡
`.tav-bubble-content`	所有气泡内容容器
`.tav-user-bubble-content`	用户气泡内容容器
`.tav-character-bubble-content`	角色气泡内容容器
`.tav-bubble-content-body`	气泡内容主体
`.tav-message-content`	消息正文
`.tav-message-attachments`	消息附件区域
`.tav-message-reasoning`	整个思考过程区域
`.tav-message-reasoning > summary`	思考过程标题
`.tav-avatar`	所有头像
`.tav-user-avatar, .tav-group-user-avatar`	用户头像，含群聊
`.tav-character-avatar, .tav-group-character-avatar`	角色头像，含群聊
`.tav-speaker-name`	发言人名称
`.tav-composer`	输入区域
`.tav-composer-shell`	输入框外壳
`.tav-composer-input`	文字输入框
`.tav-composer-add-icon`	加号图标
`.tav-composer-send-icon`	发送图标
`.tav-composer-stop-icon`	停止图标
`.tav-composer-voice-icon`	录音图标

内容容器适合设置字体，气泡外层适合设置背景、边框和阴影。正文中有单独样式的文字可能不会继承容器颜色。思考、附件、头像和名称只有在对应内容存在且启用显示时才有可见效果，具体布局也取决于气泡或平铺等显示模式。

发送、停止和录音图标随输入区状态切换，并非同时存在。停止图标用于生成停止和桌面录音停止状态。图标选择器命中的是图片，适合调整尺寸、透明度或滤镜，color 不会直接给图片改色。修改图标不等于修改按钮的点击范围。

可复制的样式

正文间距与角色气泡边框

.tav-message-content {
  line-height: 1.8;
  letter-spacing: 0.02em;
}

.tav-character-bubble {
  border: 1px solid rgba(160, 180, 220, 0.4);
  box-shadow: 0 4px 14px rgba(0, 0, 0, 0.12);
}

输入框背景、圆角与文字

.tav-composer-shell {
  background: rgba(24, 28, 40, 0.85);
  border: 1px solid rgba(180, 195, 230, 0.35);
  border-radius: 16px;
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
}

.tav-composer-input {
  color: #edf2ff;
  font-size: 16px;
}

停止图标

.tav-composer-stop-icon {
  width: 22px;
  height: 22px;
  opacity: 0.85;
}

思考标题与发言人

.tav-message-reasoning > summary {
  font-weight: 600;
  opacity: 0.8;
}

.tav-speaker-name {
  letter-spacing: 0.04em;
}

每次先加一段规则，再预览效果。避免用全局样式重排聊天页面，也不要修改输入区的定位、交互状态或事件处理。

通过 API 或工具保存 CSS

三个接口写入同一个顶层字段 customCss，值是原始 CSS 字符串，不是对象或文件路径。

接口	写入方式
TavoJS	`tavo.theme.create({ name, customCss })` 或 `tavo.theme.update(id, { customCss })`
MCP	`tavo_theme_create` 的 `theme.customCss`，或 `tavo_theme_update` 的 `patch.customCss`，更新使用 `id`
原生 Tool Calling	同名主题工具的 `theme.customCss` / `patch.customCss`，更新使用 `themeId`

创建时省略 customCss 默认是空字符串。更新时省略则保留原值，传 "" 清空，传入新字符串会替换整段 CSS，不会按选择器合并。想保留旧规则时先读取主题，再自行合并字符串。null 不是有效的清空方式。API 保存字符串不等于验证 CSS 语法或视觉效果。

const id = await tavo.theme.create({
  name: '柔和边框',
  customCss: '.tav-character-bubble { border: 1px solid rgba(160, 180, 220, 0.4); }',
})
await tavo.chat.update({ theme: id })

需要恢复时，单独执行：

await tavo.theme.update(id, { customCss: '' })

更新当前使用的主题会原位更新 WebView 样式，不需要刷新页面。创建主题本身不会自动将它应用到当前聊天。修改已有共享主题前应明确受影响的聊天。

主题 .thm 导出会在 theme.json 中以 custom_css 保存 CSS，导入后保留。旧文件缺少此字段时按空字符串处理，API 字段仍叫 customCss。外部字体或图片等 URL 资源不会因为写进 CSS 就自动打包进主题。

没有效果或布局异常时

确认已开启高级渲染，并且当前聊天正在使用保存后的主题。
从 CSS Helper 重新选择目标，核对拼写。只在录音、生成或带附件时出现的元素，需要在相应状态下检查。
检查大括号、分号、属性单位和颜色格式。编辑器提示只是语法辅助。
检查是否被更具体的规则、内联样式或消息自己的样式覆盖。不要一开始就给所有规则加 !important。
图片图标不能直接用 color 改色，原生界面和独立 iframe 内部也不会被这些规则修改。
无法定位时先备份 CSS，再清空并保存。确认恢复后逐段加回规则，定位造成问题的部分。

目录