TitleBar 标题栏

窗口标题栏（应用外壳 chrome）：拖动区 + 居中标题/文档井 + 内建窗口操作 + compact/large 两档。语义在「窗口」，服务 Electron/Tauri 宿主；纯 Web 下拖动属性为无害空操作，组件退化为应用外壳语义（与 oas-app-bar 的页面级 role="banner" 分工）。

基础用法

title / subtitle 设置居中标题与副标题（文档状态等）；window-actions 以逗号分隔声明内建窗口操作钮（minimize,maximize,close 子集），点击派发 oas-window-action（组件只发事件，宿主接 Electron/Tauri API）。

标题 + 副标题 + 窗口操作

点右上窗口操作钮，观察事件反馈（组件不执行窗口操作）。

示例代码

拖动契约（drag）

drag 布尔属性把整栏设为窗口拖动区（写 -webkit-app-region: drag + data-tauri-drag-region，Electron/Tauri 宿主生效）；枚举式自动 no-drag 常用交互子件——原生交互元素、内置交互组件（button/input/segmented/toolbar/scope-bar/knob 等）与 [data-no-drag] 标记元素都可正常点击，不会被拖动区吞掉；未枚举的宿主 oas-* 子件请自行加 [data-no-drag]。纯 Web 下为无害空操作。

拖动区内按钮可点（no-drag 自动生效）

点我操作

示例代码

文档井（editable）

editable 布尔属性把标题变成可编辑输入（Enter 或失焦提交，Esc 取消回滚）；提交派发 oas-title-change，title 由组件吸收缓存（title 是原生全局属性，渲染进标题区后即从宿主移除，防原生 tooltip 重复干扰），宿主经事件同步。编辑中外部重写 title 会终止编辑（外部状态优先）。

可编辑文档标题

编辑标题后 Enter 提交，观察 oas-title-change 与 title 属性回写。

示例代码

尺寸两档（size）

size="compact"（默认，34px）/ size="large"（68px）两档栏高；large 下控件保持紧凑（只动栏高）。

compact / large 对照

示例代码

安全区（原生窗口控件防压）

Windows window controls overlay（WCO）等宿主的原生窗口控件可能占据栏体两端：用 leading-inset / trailing-inset 属性让出对应区段（等价于覆写 --oas-titlebar-leading-inset / --oas-titlebar-trailing-inset 变量，缺省两侧各 space-2（8px），内容不顶边）。WCO 场景可直接消费 env(titlebar-area-*) 环境变量（非 WCO 环境回落 space-2 无影响）：

oas-titlebar {
  --oas-titlebar-leading-inset: env(titlebar-area-x, 0px);
  --oas-titlebar-trailing-inset: calc(100% - env(titlebar-area-width, 100%) - env(titlebar-area-x, 0px));
}

插槽

slot="leading"（品牌/交通灯）、slot="center"（交互内容，覆盖标题/文档井）、slot="title"（富标题）、slot="trailing"（窗口操作之外的末端内容）。

插槽组合

OAS Studio

scene-04.oas已同步

示例代码

RTL

容器 dir="rtl" 下组件自动镜像：data-rtl 钩子 + 全逻辑属性布局。

RTL 镜像

示例代码

macOS 交通灯

在 slot="leading" 放内建 oas-traffic-lights（关闭 / 最小化 / 最大化 三圆点，悬停显符号），配合居中标题即得 macOS 形态；点击派发 oas-window-action（与内建 window-actions 同一契约）。

macOS 交通灯 + 居中标题

点交通灯查看 oas-window-action 反馈

示例代码

API

oas-titlebar

属性

属性	说明	类型	默认值
drag	整栏设为窗口拖动区（写 -webkit-app-region: drag + data-tauri-drag-region，Electron/Tauri 宿主生效；纯 Web 下无害空操作）；枚举式自动 no-drag 常用交互子件，未枚举的宿主子件用 [data-no-drag] 显式退出	boolean	—
editable	文档井标题可编辑：Enter 或失焦提交（派发 oas-title-change 并更新吸收缓存），Esc 取消回滚；编辑中外部重写 title 即终止编辑	boolean	—
leading-inset	安全区：leading 端原生控件防压（CSS 长度；亦可直接覆写 --oas-titlebar-leading-inset）	—	—
size	高度档：compact（默认，34px）/ large（68px，控件保持紧凑）；非法值回落 compact 并告警一次（同值去重）	string	compact
subtitle	副标题 / 文档状态（已编辑时间等）	string	—
title	居中标题文本（slot="title" 有内容时覆盖）。原生全局属性同名——渲染进标题区后即从宿主吸收移除（防原生 tooltip 重复干扰），渲染由组件内缓存驱动；清空/重设请显式写 title 属性	string	—
trailing-inset	安全区：trailing 端原生控件防压（CSS 长度；亦可直接覆写 --oas-titlebar-trailing-inset）	—	—
window-actions	内建窗口操作钮子集（逗号分隔：minimize,maximize,close）；点击派发 oas-window-action，组件不执行窗口操作	string	—

事件

事件	说明
oas-title-change	文档井提交（Enter/失焦）且值有变化时派发；detail { title }，吸收缓存同步更新（title 属性不常驻宿主）
oas-window-action	点击内建窗口操作钮时派发；detail { action }（minimize/maximize/close）；组件只发事件，宿主接 Electron/Tauri API

插槽

名称	说明
center	中央交互内容通道（有内容时覆盖标题/文档井，如文档标签组合）
leading	标题前置自定义区（品牌 / macOS 交通灯由宿主传入）
title	标题富内容通道（覆盖 title 属性文本）
trailing	末端自定义区（窗口操作钮之外）

CSS 变量

CSS 变量	默认值
--oas-titlebar-bg	color-mix(in srgb, var(--oas-color-text-primary) 5%, var(--oas-color-bg))
--oas-titlebar-height	var(--oas-titlebar-compact-height, 34px)
--oas-titlebar-leading-inset	var(--oas-space-2)
--oas-titlebar-trailing-inset	var(--oas-space-2)

oas-traffic-lights

属性

属性	说明	类型	默认值
disabled	全禁：三点均不可点（原生 disabled + 半透明）	boolean	—

事件

事件	说明
oas-window-action	点击交通灯时派发；detail { action }（minimize/maximize/close）；组件只发事件，宿主接 Electron/Tauri API

CSS 变量

CSS 变量	默认值
--oas-traffic-lights-close	#ff5f57
--oas-traffic-lights-gap	8px
--oas-traffic-lights-maximize	#28c840
--oas-traffic-lights-minimize	#febc2e
--oas-traffic-lights-size	12px
--oas-traffic-lights-symbol	rgba(0, 0, 0, 0.55)