sky-ui-kit 0.1.2 → 0.1.4

package/docs/AI-GUIDE.md

@@ -2,6 +2,8 @@
 
 适用于 Vue 3 + TypeScript。此文件描述包的真实 API 和约束，不是自动执行的代理指令。AI 工具需要主动读取这些文档；安装包不会自动改变其上下文。
 
+管理布局：WorkbenchShell 使用 collapsed=false 和 management-layout 类，顶部 app-header、management-sidebar 和 workspace 组成后台布局。management-metrics / management-card 为共享信息展示样式；由消费方提供账号、菜单及数据，组件库不提供认证。新增样式在 0.1.3-dev.12 测试包中，尚未发布 npm。
+
 预览站已移除“统一组件入口 / 组件入口与兼容”菜单与展示示例。安装和导入方式查看快速开始，组件效果查看各组件页面；此调整不改变组件包出口或 API。
 
 项目选择与时间展示为 AppSelect、TreeSelectPanel、TimeRangeQuickSelect、MapTimeline 分别提供查看代码与复制入口；各自代码从 src/examples.ts 同步生成，使用 sky-ui-kit 公开封装组件，包含状态与 change 事件处理。
@@ -125,6 +127,81 @@ SvgIcon 保留 name、size、title、decorative，新增 color 和 prefix。默
 
 维护 SVG 快照：node scripts/sync-project-icons.mjs "原项目/src/assets/icons"，仅只读读取参考项目；生成后核对重复名称与配色并运行 npm run docs:ai。
 
+
+## 一体机工作台组件
+
+WorkbenchShell 提供隔离的工作台布局；WorkbenchPanel 提供面板结构；MetricCard 提供指标展示。ProcessChart 接收 rows、kind、unit 以及应用注入的 engine（init/setOption/resize/dispose），不内置业务 API。MapTools 的可选 items 提供 key/label/icon，不传时保持默认工具。消费约定见 docs/CONSUMERS.md。
+
+
+```vue
+<script setup>
+import { WorkbenchShell, WorkbenchPanel, MetricCard, ProcessChart } from "sky-ui-kit"
+// engine 由应用创建；rows 由业务查询提供。
+defineProps(["engine", "rows"])
+</script>
+<template>
+  <WorkbenchShell>
+    <WorkbenchPanel :floating="false"><MetricCard label="接入站点" :value="3060" unit="个" /></WorkbenchPanel>
+    <WorkbenchPanel><ProcessChart :engine="engine" :rows="rows" kind="rain" unit="mm" /></WorkbenchPanel>
+  </WorkbenchShell>
+</template>
+```
+
+
+## 2026-10-13：顶部菜单修复（0.1.3-dev.1）
+
+删除工作台残留的 primary-nav 样式，选中效果由 ProjectMenu 统一负责。顶部菜单按内容宽度居中，不再拉满或撑满头部高度；横向菜单不换行，仅允许横向滚动并隐藏滚动条，保留滚轮、触摸和键盘操作。应用升级本地开发包，未发布 npm。
+
+
+## 2026-10-13：左侧胶囊布局（0.1.3-dev.2）
+
+工作台左侧采用留白悬浮圆角侧栏，内部菜单使用胶囊圆角，移除选中项侧边竖线和嵌套菜单外框。数据范围卡片统一圆角。样式限定 sky-workbench，不改变独立 ProjectMenu。更新本地消费包，未发布 npm。
+
+
+## 2026-10-13：地图布局（0.1.3-dev.3）
+
+一体机应用彻底移除左侧工作台、数据范围及侧栏开关，导航由顶部菜单提供。WorkbenchShell collapsed=true 使用单列布局，地图占满导航下方；指标、列表、工具和过程图保持悬浮。修复 collapsed 根节点选择器，取消地图定位的侧栏留白。该布局替代此前胶囊侧栏方案。
+
+
+## 地图左侧胶囊导航（0.1.3-dev.4）
+
+移除顶部横向菜单，使用 ProjectMenu 在地图左侧悬浮展示五个胶囊入口；不占侧栏列、不恢复数据范围与终端信息。工作台提供 map-capsule-menu 样式变体。
+
+
+## 透明地图顶部栏（0.1.3-dev.5）
+
+地图布局下头部绝对定位悬浮，无背景、边框或阴影；地图延伸至页面顶部。业务标题、指标、列表保留顶部避让。独立带侧栏布局不受影响。
+
+
+## 地图排版统一（0.1.3-dev.6）
+
+左侧标题与胶囊导航对齐，去除重复面包屑及介绍；四项指标合为紧凑统计栏。右侧与过程面板使用实底、统一圆角和留白，图例固定左下。过程图初始隐藏，查询站点或预报后打开。
+
+
+## 顶部可读性与地图穿透（0.1.3-dev.7）
+
+品牌和操作按钮分组使用实底胶囊，顶部整条容器 pointer-events:none，仅品牌及操作区恢复 auto。空白处拖拽、滚轮交给地图；去掉冗余本地应用文字和分隔线。
+
+
+## 使用正式地图胶囊菜单（0.1.3-dev.8）
+
+一体机左侧改用已有 MapSideMenu，保留搜索、图标模式、分组折叠及选中样式。替代此前 ProjectMenu 的自定义胶囊变体。工作台只提供定位，不另写菜单皮肤。
+
+
+## 一级地图胶囊菜单（0.1.3-dev.9）
+
+MapSideMenu 新增 flat:boolean，默认 false 保持分组模式。flat=true 隐藏父节点，将各项显示为一级胶囊，去除缩进及连线。一体机使用 flat=true 展示五个主菜单。
+
+
+## 图层控制封装（0.1.3-dev.10）
+
+MapLayerControl 参考平台 LayerControl/LayerTreeNode，提供底图选择、注记、树分组、搜索、显隐、拖拽排序、透明度、定位与可移除图层事件。数据及地图操作由消费方提供，未绑定平台 Pinia 或假服务。
+
+
+## 地图胶囊选中修复（0.1.3-dev.11）
+
+flat 模式按钮此前错误使用 child 类而内部图标、文字使用 parent 类，导致 active 样式不匹配。统一按钮及内容层级类，保留现有单选、多选及事件逻辑。
+
 <!-- GENERATED EXAMPLES -->
 
 ### 快速开始：安装最新正式版本
@@ -868,34 +945,20 @@ const items = [{ key: 'overview', label: '运行概览' }, { key: 'data', label:
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
-import { UiButton } from 'sky-ui-kit'
+import { TemplateLayout, UiButton, MapTools, WorkbenchPanel } from 'sky-ui-kit'
 const rightOpen = ref(true)
-const timelineVisible = ref(true)
 </script>
 <template>
-  <div class="template-demo" :class="{ 'right-open': rightOpen }">
-    <div class="map-placeholder">地图宿主（由 MainLayoutMap 提供）</div>
-    <div class="top-region">top · 标题 / 查询条件</div>
-    <div class="toolbar-region"><span>toolbar · 地图工具</span><UiButton size="small" @click="rightOpen = !rightOpen">{{ rightOpen ? '收起右栏' : '展开右栏' }}</UiButton><UiButton size="small" @click="timelineVisible = !timelineVisible">切换时间轴</UiButton></div>
-    <aside v-if="rightOpen" class="right-region">right · 业务面板<br>测站详情 / 过程数据</aside>
-    <div class="content-region">content · 业务浮层</div>
-    <div class="legend-region" :class="{ 'above-timeline': timelineVisible }">legend · 图例</div>
-    <div v-if="timelineVisible" class="timeline-region">timeline · 实况 / 预报时间轴</div>
+  <div style="position: relative; height: 460px">
+    <TemplateLayout :right-open="rightOpen">
+      <template #top><UiButton @click="rightOpen = !rightOpen">{{ rightOpen ? '收起右栏' : '展开右栏' }}</UiButton></template>
+      <template #toolbar><MapTools :items="[{ key: 'layers', label: '图层' }]" /></template>
+      <template #right><WorkbenchPanel style="height: 100%">right · 业务面板</WorkbenchPanel></template>
+      <template #legend>legend · 图例</template>
+      <template #timeline>timeline · 时间轴</template>
+    </TemplateLayout>
   </div>
 </template>
-<style scoped>
-.template-demo { position: relative; height: 360px; overflow: hidden; border: 2px solid var(--color-border, #c5d2e5); border-radius: 8px; --demo-panel-width: min(220px, 30%); --demo-right-offset: 12px; }
-.right-open { --demo-right-offset: calc(var(--demo-panel-width) + 24px); }
-.map-placeholder { position: absolute; inset: 0; display: grid; place-items: center; color: var(--color-muted, #748096); background-color: var(--color-surface, #f4f7fb); background-image: linear-gradient(var(--color-border, #dbe3ef) 1px, transparent 1px), linear-gradient(90deg, var(--color-border, #dbe3ef) 1px, transparent 1px); background-size: 32px 32px; }
-.top-region, .toolbar-region, .right-region, .content-region, .legend-region, .timeline-region { position: absolute; padding: 12px; box-sizing: border-box; border: 1px solid var(--color-primary, #1677ff); border-radius: 6px; background: var(--color-panel, white); color: var(--color-text, #1f2937); }
-.top-region { top: 12px; left: 12px; }
-.toolbar-region { top: 64px; right: var(--demo-right-offset); display: flex; gap: 8px; align-items: center; flex-wrap: wrap; max-width: 65%; }
-.right-region { top: 12px; right: 12px; bottom: 12px; width: var(--demo-panel-width); }
-.content-region { top: 124px; left: 12px; }
-.legend-region { bottom: 12px; right: var(--demo-right-offset); }
-.legend-region.above-timeline { bottom: 76px; }
-.timeline-region { bottom: 12px; left: 12px; right: var(--demo-right-offset); text-align: center; }
-</style>
 
 ```
 
@@ -2847,3 +2910,31 @@ const popoverRef = ref()
 </style>
 
 ```
+
+### 地图菜单多选示例
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Pouring, List, Sunny } from '@element-plus/icons-vue'
+import { MapSideMenu, UiButton } from 'sky-ui-kit'
+const activeKeys = ref(['rain', 'water'])
+const compactKeys = ref(['rain', 'temperature'])
+const message = ref('可同时选择多个监测要素，再次点击取消')
+const items = [{ key: 'rain', label: '降水', icon: Pouring }, { key: 'water', label: '水位', icon: List }, { key: 'temperature', label: '气温', icon: Sunny }]
+</script>
+<template>
+  <h3>地图胶囊菜单 · 多选</h3>
+  <div class="multi-menu"><MapSideMenu multiple v-model:active-keys="activeKeys" :items="items" @change="message = '已选：' + $event.join('、')" /></div>
+  <p>当前选择：{{ activeKeys.join('、') || '无' }}</p>
+  <UiButton @click="activeKeys = []">清空选择</UiButton>
+  <h3>纯图标 · 多选</h3>
+  <div class="multi-menu"><MapSideMenu multiple compact v-model:active-keys="compactKeys" :items="items" /></div>
+  <p>图标选择：{{ compactKeys.join('、') || '无' }}</p>
+  <p role="status">{{ message }}</p>
+</template>
+<style scoped>
+.multi-menu { height: 260px; border: 1px solid var(--color-border, #dbe3ef); border-radius: 8px; background: var(--surface-subtle, #eef5ff); }
+</style>
+
+```

package/docs/COMPONENT-API.md

@@ -201,8 +201,11 @@ export interface ProjectMenuGroup { label: string; items: ProjectMenuItem[] }
 
 | Name | Type | Required | Default expression |
 |---|---|---|---|
+| flat | boolean | false | false |
 | title | string | false | '实况(测站)' |
 | active | string | false | 'rain' |
+| multiple | boolean | false | false |
+| activeKeys | string[] | false | () => [] |
 | dark | boolean | false | false |
 | compact | boolean | false | false |
 | items | MapMenuItem[] | false | () => [
@@ -218,6 +221,8 @@ export interface ProjectMenuGroup { label: string; items: ProjectMenuItem[] }
 ### Events
 
 - `update:active` — `[key: string]`
+- `update:activeKeys` — `[keys: string[]]`
+- `change` — `[keys: string[]]`
 - `update:compact` — `[value: boolean]`
 - `select` — `[item: MapMenuItem]`
 
@@ -236,6 +241,7 @@ export interface MapMenuItem { key: string; label: string; icon?: Component }
 | active | string | false | 'layers' |
 | horizontal | boolean | false | false |
 | icons | Record<string, Component> | false | () => ({}) |
+| items | MapToolItem[] | false | undefined / no declared default |
 
 ### Events
 
@@ -245,6 +251,10 @@ export interface MapMenuItem { key: string; label: string; icon?: Component }
 
 Slots: No declared content slots.
 
+```ts
+export interface MapToolItem { key: string; label: string; icon?: Component }
+```
+
 ## AtlasMapTitle
 
 ### Props
@@ -293,6 +303,120 @@ No declared events.
 
 Slots: No declared content slots.
 
+## WorkbenchShell
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| collapsed | boolean | false | false |
+
+### Events
+
+No declared events.
+
+Slots: default
+
+## WorkbenchPanel
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| as | 'section' &#124; 'aside' &#124; 'div' | false | 'section' |
+| floating | boolean | false | true |
+
+### Events
+
+No declared events.
+
+Slots: default
+
+## MetricCard
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| label | string | true | undefined / no declared default |
+| value | string &#124; number | false | '—' |
+| unit | string | false | '' |
+| tone | 'blue' &#124; 'cyan' &#124; 'green' &#124; 'purple' | false | 'blue' |
+| compact | boolean | false | false |
+
+### Events
+
+No declared events.
+
+Slots: icon
+
+## ProcessChart
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| rows | ProcessChartRow[] | true | undefined / no declared default |
+| engine | ProcessChartEngine | true | undefined / no declared default |
+| kind | 'rain' &#124; 'flow' &#124; 'line' | false | 'rain' |
+| unit | string | false | '' |
+| label | string | false | undefined / no declared default |
+
+### Events
+
+No declared events.
+
+Slots: No declared content slots.
+
+```ts
+export interface ProcessChartRow { time: string; value: number | null }
+export interface ProcessChartInstance { setOption: (option: Record<string, unknown>, notMerge?: boolean) => void; resize: () => void; dispose: () => void }
+export interface ProcessChartEngine { init: (element: HTMLElement) => ProcessChartInstance }
+```
+
+## MapLayerControl
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| nodes | MapLayerNode[] | true | undefined / no declared default |
+| basemap | string | false | 'imagery' |
+| annotation | boolean | false | true |
+
+### Events
+
+- `update:basemap` — `[value: string]`
+- `update:annotation` — `[value: boolean]`
+- `visibility` — `[node: MapLayerNode, visible: boolean]`
+- `opacity` — `[node: MapLayerNode, value: number]`
+- `move` — `[dragId: string, targetId: string, position: string]`
+- `remove` — `[node: MapLayerNode]`
+- `locate` — `[node: MapLayerNode]`
+- `close` — `[]`
+
+Slots: No declared content slots.
+
+```ts
+export interface MapLayerNode { id: string; name: string; visible?: boolean; opacity?: number; disabled?: boolean; removable?: boolean; children?: MapLayerNode[] }
+```
+
+## TemplateLayout
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| rightOpen | boolean | false | false |
+| rightPanelEnabled | boolean | false | true |
+| rightPanelWidth | string | false | '' |
+
+### Events
+
+No declared events.
+
+Slots: top, toolbar, right, legend, timeline, content, default
+
 ## UiAffix
 
 固钉 · 导航组件. Original: ElAffix. Import from: sky-ui-kit. [API](https://element-plus.org/zh-CN/component/affix.html). See dist/components/element-plus.d.ts.

package/docs/COMPONENT-GUIDE.md

@@ -1,160 +1,163 @@
-# 组件使用说明
-
-本指南说明当前包已导出的 11 个项目组件的用途、数据约定和交互边界。完整属性类型、默认值、事件签名和插槽列表见 [组件 API](COMPONENT-API.md)；完整示例见 [AI-GUIDE](AI-GUIDE.md)。原项目组件清单中的文件不一定已经进入本包，以 `src/components/index.ts` 和 `components.json` 为准。
-
-## SvgIcon 与原项目适配
-
-SvgIcon 按 name 显示项目 SVG，size 为 CSS 尺寸或按 --cp-font-1 缩放的数字，color 默认继承。title / decorative 控制无障碍说明。内置资源使用默认 sky-icon- 前缀并自动注册；自有资源需要 Vite SVG 插件、main.ts 注册和 prefix="icon-"，完整可复制步骤见 AI-GUIDE.md。当前原项目已配置 icon-[name]，不要重复安装注册；新项目建议 icon-[dir]-[name] 避免同名冲突。原生属性和事件透传 SVG，无内容插槽；固定色路径保留配色，未知名称不显示图形。
-
-实际组件使用清单见 [COMPONENT-USAGE.md](COMPONENT-USAGE.md)，逐模块替换边界和路由/地图/主题适配见 [ADAPTATION.md](ADAPTATION.md)。这些文档明确哪些组件可替换、需要适配层或仍留业务项目。
-
-## 公共接入
-
-需要 Vue 3，项目声明的 peerDependencies 为 Vue `^3.4.21`、Element Plus `^2.14.7`、图标包 `^2.3.2` 和 motion-v `^2.3.0`。这些是依赖声明范围，不代表已经验证整个版本范围。
-
-在应用入口加载一次样式：
-
-```ts
-import 'element-plus/dist/index.css'
-import 'sky-ui-kit/style.css'
-```
-
-组件按名称从 `sky-ui-kit` 或 `sky-ui-kit/components` 导入。无需引入预览站的 Pinia 主题 store。暗色、局部主题和浮层挂载规则见 [CSS-THEME](CSS-THEME.md)。
-
-## 如何选择组件
-
-| 需求 | 组件 | 主要数据 / 控制方式 |
-|---|---|---|
-| 标准 Element Plus 控件 | Ui 前缀组件 | 使用对应 Element Plus API |
-| 使用 options 的项目下拉框 | AppSelect | v-model + options |
-| 按行政区、流域等分类选择树节点 | TreeSelectPanel | v-model + categories |
-| 切换预设时间范围 | TimeRangeQuickSelect | v-model + options |
-| 选择、播放实况和预报帧 | MapTimeline | v-model 帧索引 |
-| 普通横向 / 纵向菜单 | ProjectMenu | v-model:active + items / groups |
-| 单分类地图胶囊菜单 | MapSideMenu | v-model:active / compact |
-| 地图工具按钮 | MapTools | v-model:active + tool-click |
-| 地图居中标题 | AtlasMapTitle | title / subtitle / rightOpen |
-| 右侧面板开关按钮 | AtlasRightToggleButton | open + toggle |
-| 多序列按时间对齐的表格 | ProcessDataTable | times + series |
-
-## AppSelect
-
-基于 ElSelectV2，适合站点等选项列表。`options` 可以是字符串、数字，或 `{ label, value, disabled? }` 对象；字符串、数字自动以自身作为值，显示文字转换为字符串。
-
-- `v-model` 保存选项值；多选时使用数组，并传入 `multiple`。
-- `emptyLabel` 同时用于无数据、无搜索匹配提示。
-- `filterable`、`clearable`、`disabled`、`placeholder` 等通过属性透传到 ElSelectV2，语义以对应官方 API 为准。
-- `change` 返回值，非整个选项对象。没有声明内容插槽，不使用 `el-option` 子节点；需要子节点选项时用 UiSelect。
-- `teleported` 默认 false；父容器的 overflow 可能影响浮层显示。
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { AppSelect } from 'sky-ui-kit'
-const station = ref('hankou')
-const options = [{ label: '汉口站', value: 'hankou' }, { label: '宜昌站', value: 'yichang' }]
-</script>
-<template>
-  <AppSelect v-model="station" :options="options" filterable clearable />
-</template>
-```
-
-## TreeSelectPanel
-
-`categories` 为 `{ type, label, children }[]`，每个树节点至少提供 `id` 和 `label`，子节点放在 `children`。节点 ID 应保持稳定并避免跨分类重复，以免选中值含义不明确。
-
-- `v-model` 是节点 ID，类型为 string、number 或 null，非节点对象。
-- `change` 返回 `{ node, category }`；`select` 以两个参数返回节点和分类。两种事件用于同一次选择的不同接线方式，避免重复执行同一业务请求。
-- `defaultActiveType` 指定初始分类；`defaultExpandAll` 控制默认展开。
-- `closeOnSelect`、`closeOnMouseLeave` 控制关闭行为；`dark` 控制组件暗色外观。
-- `placeholder`、`searchPlaceholder`、`emptyText` 分别用于选择框、搜索框和无数据提示。数据获取、权限过滤由应用处理。
-
-## TimeRangeQuickSelect
-
-`modelValue` 和 `options` 必填。每项为 `{ key, label, amount?, unit? }`，`key` 建议唯一，选中值应与某个 key 一致。
-
-- `v-model` 保存 key；`change` 返回完整选项。
-- `amount`、`unit` 可用于应用计算查询范围，unit 为 hour 或 day。组件负责选择，不自动生成起止时间或发起查询。
-- `ariaLabel` 为控件提供可访问名称。
-
-## MapTimeline
-
-适合按时间帧切换地图图层。`v-model` 是数值索引；`change` 返回包含 `time`、`value`、`label`、`kind` 等字段的 TimelinePoint，应用据此加载对应业务数据。
-
-- 可传入 `points` 明确指定帧数据，或使用 `startTime`、`steps`、`interval`、`unit` 等生成时间点。自定义点的数据结构见 API 中的 TimelinePoint。
-- `pastSteps`、`futureSteps` 用于实况 / 预报分段；`forecastCount`、`minTime`、`maxTime` 等高级参数需结合具体数据核对，避免把帧数和时间值混用。
-- `v-model:playing` 和 `v-model:speed` 同步播放状态与倍速；`internalPlayback` 控制是否由组件内部推进播放，外部驱动时应用需要自行更新索引。
-- `pageSize` 控制展示分页，`loop` 控制循环；`showScale`、`showCurrentMarker` 控制刻度及当前时间标记。
-- 明确提供 `timeZone` 和带时区的时间字符串，例如 `2026-10-08T08:00:00+08:00`，避免使用含义依赖设备时区的字符串。
-- 提供 `date-select` 插槽，参数为 start-time、active-point、active-index、value、set-start-time 和 jump-to-time，可接入自定义日期选择器。组件不负责接口请求、缓存或地图渲染。
-
-## ProjectMenu
-
-`direction` 为 horizontal 或 vertical。横向布局读取 `items`，纵向布局读取 `groups`，切换 direction 时需要提供对应数据。`items` 为 `{ key, label, disabled?, icon? }[]`，`groups` 为 `{ label, items }[]`。具体布局示例见 AI-GUIDE。
-
-- `v-model:active` 同步选中 key；`select` 返回完整菜单项。
-- `disabled` 禁止选择；纵向菜单的 `icon` 接收 Vue 图标组件，不是图标名称字符串。横向菜单当前只显示文字。
-- 路由跳转、权限控制由应用在 select 中处理；分组折叠由组件内部处理。
-
-## MapSideMenu
-
-提供一个分类标题及其子菜单，支持按 label 搜索、分类展开和纯图标模式。`items` 为 `{ key, label, icon? }[]`，不具有 ProjectMenu 的 disabled 字段。
-
-- `v-model:active` 同步选中 key，`select` 返回菜单项。
-- `v-model:compact` 同步纯图标状态，`dark` 控制暗色外观。
-- 搜索和分类展开属于内部状态，没有相应的公开双向绑定。
-- 容器应提供明确高度，组件本身使用 height: 100%。切换图层和路由由应用处理。
-
-## MapTools
-
-工具 key 固定为 layers、module、refresh、locate、settings、analysis、context。`horizontal` 切换横向排列；`icons` 按 key 覆盖图标，值为 Vue 组件。
-
-- 点击任意工具均触发 `tool-click(key)`。
-- layers、module、settings、analysis 切换 active；再次点击当前项会取消选中并返回空字符串。
-- refresh、locate 触发动作，不修改 active。
-- context 使用独立内部状态，触发 `context-change(enabled)`；没有 `v-model:context`。
-- 组件仅提供按钮交互。地图定位、刷新、图层面板与空间分析由应用通过事件实现。
-
-## AtlasMapTitle
-
-`title` 必填；`subtitle` 默认空字符串，`rightOpen` 默认 false。
-
-标题使用绝对定位，建议父容器设置 `position: relative`。`rightOpen` 调整标题右侧留白，宽度使用主题变量 `--userssite-rightpanel-width`；应与应用右面板宽度一致。标题使用 pointer-events: none，没有点击事件或插槽。
-
-## AtlasRightToggleButton
-
-`open` 表示外部面板状态；点击触发无参数 `toggle`，组件不自行更新 open。`openTitle`、`closeTitle` 同时用于按钮标题和 aria-label。
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { AtlasRightToggleButton } from 'sky-ui-kit'
-const open = ref(false)
-</script>
-<template>
-  <AtlasRightToggleButton :open="open" @toggle="open = !open" />
-  <aside v-if="open">面板内容</aside>
-</template>
-```
-
-## ProcessDataTable
-
-`times: string[]` 和 `series: { name: string; data: (number | null)[] }[]` 必填。第 i 个时间对应每个 series.data[i]；调用方应按相同时间顺序对齐数据。
-
-- `loading` 显示“查询中…”；times 为空显示“暂无数据”。
-- null 或缺失值显示“—”，0 仍显示为 0。
-- 内部每页固定 100 条，替换 times 数组时重置到首页。
-- 当前没有 pageSize、分页事件、排序、单元格插槽或远程分页 API。需要这些能力时使用 UiTable 组合实现。
-
-## 网站组件页还需要补充的内容
-
-当前指南补齐说明层，后续网站每个组件页面应把以下信息放在对应演示旁边：
-
-1. 中文用途及组件选择建议。
-2. 独立可复制示例，覆盖基础用法、受控状态和实际支持的边界状态。
-3. 带中文语义说明的 Props、Events、Slots 表；如有公开实例方法，再列 Exposes。
-4. 数据结构、事件载荷示例、样式变量与容器要求。
-5. 已验证的键盘交互、暗色与浮层行为；未验证内容不要标记为支持。
-6. 版本变更和已知限制，区分已导出组件、预览示例与尚未迁入的业务组件。
-
-Ui 基础组件已统一关联对应 Element Plus 主组件文档，例如 TableColumn 对应 Table 页面、FormItem 对应 Form 页面。完整组件、子组件、服务和指令清单见 [ELEMENT-PLUS-COVERAGE](ELEMENT-PLUS-COVERAGE.md)。独立示例与视觉状态仍需逐项补充和验证。
+# 组件使用说明
+
+本指南说明当前包已导出的 11 个项目组件的用途、数据约定和交互边界。完整属性类型、默认值、事件签名和插槽列表见 [组件 API](COMPONENT-API.md)；完整示例见 [AI-GUIDE](AI-GUIDE.md)。原项目组件清单中的文件不一定已经进入本包，以 `src/components/index.ts` 和 `components.json` 为准。
+
+## SvgIcon 与原项目适配
+
+SvgIcon 按 name 显示项目 SVG，size 为 CSS 尺寸或按 --cp-font-1 缩放的数字，color 默认继承。title / decorative 控制无障碍说明。内置资源使用默认 sky-icon- 前缀并自动注册；自有资源需要 Vite SVG 插件、main.ts 注册和 prefix="icon-"，完整可复制步骤见 AI-GUIDE.md。当前原项目已配置 icon-[name]，不要重复安装注册；新项目建议 icon-[dir]-[name] 避免同名冲突。原生属性和事件透传 SVG，无内容插槽；固定色路径保留配色，未知名称不显示图形。
+
+实际组件使用清单见 [COMPONENT-USAGE.md](COMPONENT-USAGE.md)，逐模块替换边界和路由/地图/主题适配见 [ADAPTATION.md](ADAPTATION.md)。这些文档明确哪些组件可替换、需要适配层或仍留业务项目。
+
+## 公共接入
+
+需要 Vue 3，项目声明的 peerDependencies 为 Vue `^3.4.21`、Element Plus `^2.14.7`、图标包 `^2.3.2` 和 motion-v `^2.3.0`。这些是依赖声明范围，不代表已经验证整个版本范围。
+
+在应用入口加载一次样式：
+
+```ts
+import 'element-plus/dist/index.css'
+import 'sky-ui-kit/style.css'
+```
+
+组件按名称从 `sky-ui-kit` 或 `sky-ui-kit/components` 导入。无需引入预览站的 Pinia 主题 store。暗色、局部主题和浮层挂载规则见 [CSS-THEME](CSS-THEME.md)。
+
+## 如何选择组件
+
+| 需求 | 组件 | 主要数据 / 控制方式 |
+|---|---|---|
+| 标准 Element Plus 控件 | Ui 前缀组件 | 使用对应 Element Plus API |
+| 使用 options 的项目下拉框 | AppSelect | v-model + options |
+| 按行政区、流域等分类选择树节点 | TreeSelectPanel | v-model + categories |
+| 切换预设时间范围 | TimeRangeQuickSelect | v-model + options |
+| 选择、播放实况和预报帧 | MapTimeline | v-model 帧索引 |
+| 普通横向 / 纵向菜单 | ProjectMenu | v-model:active + items / groups |
+| 单分类地图胶囊菜单 | MapSideMenu | v-model:active / compact |
+| 地图工具按钮 | MapTools | v-model:active + tool-click |
+| 地图居中标题 | AtlasMapTitle | title / subtitle / rightOpen |
+| 右侧面板开关按钮 | AtlasRightToggleButton | open + toggle |
+| 多序列按时间对齐的表格 | ProcessDataTable | times + series |
+
+## AppSelect
+
+基于 ElSelectV2，适合站点等选项列表。`options` 可以是字符串、数字，或 `{ label, value, disabled? }` 对象；字符串、数字自动以自身作为值，显示文字转换为字符串。
+
+- `v-model` 保存选项值；多选时使用数组，并传入 `multiple`。
+- `emptyLabel` 同时用于无数据、无搜索匹配提示。
+- `filterable`、`clearable`、`disabled`、`placeholder` 等通过属性透传到 ElSelectV2，语义以对应官方 API 为准。
+- `change` 返回值，非整个选项对象。没有声明内容插槽，不使用 `el-option` 子节点；需要子节点选项时用 UiSelect。
+- `teleported` 默认 false；父容器的 overflow 可能影响浮层显示。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { AppSelect } from 'sky-ui-kit'
+const station = ref('hankou')
+const options = [{ label: '汉口站', value: 'hankou' }, { label: '宜昌站', value: 'yichang' }]
+</script>
+<template>
+  <AppSelect v-model="station" :options="options" filterable clearable />
+</template>
+```
+
+## TreeSelectPanel
+
+`categories` 为 `{ type, label, children }[]`，每个树节点至少提供 `id` 和 `label`，子节点放在 `children`。节点 ID 应保持稳定并避免跨分类重复，以免选中值含义不明确。
+
+- `v-model` 是节点 ID，类型为 string、number 或 null，非节点对象。
+- `change` 返回 `{ node, category }`；`select` 以两个参数返回节点和分类。两种事件用于同一次选择的不同接线方式，避免重复执行同一业务请求。
+- `defaultActiveType` 指定初始分类；`defaultExpandAll` 控制默认展开。
+- `closeOnSelect`、`closeOnMouseLeave` 控制关闭行为；`dark` 控制组件暗色外观。
+- `placeholder`、`searchPlaceholder`、`emptyText` 分别用于选择框、搜索框和无数据提示。数据获取、权限过滤由应用处理。
+
+## TimeRangeQuickSelect
+
+`modelValue` 和 `options` 必填。每项为 `{ key, label, amount?, unit? }`，`key` 建议唯一，选中值应与某个 key 一致。
+
+- `v-model` 保存 key；`change` 返回完整选项。
+- `amount`、`unit` 可用于应用计算查询范围，unit 为 hour 或 day。组件负责选择，不自动生成起止时间或发起查询。
+- `ariaLabel` 为控件提供可访问名称。
+
+## MapTimeline
+
+适合按时间帧切换地图图层。`v-model` 是数值索引；`change` 返回包含 `time`、`value`、`label`、`kind` 等字段的 TimelinePoint，应用据此加载对应业务数据。
+
+- 可传入 `points` 明确指定帧数据，或使用 `startTime`、`steps`、`interval`、`unit` 等生成时间点。自定义点的数据结构见 API 中的 TimelinePoint。
+- `pastSteps`、`futureSteps` 用于实况 / 预报分段；`forecastCount`、`minTime`、`maxTime` 等高级参数需结合具体数据核对，避免把帧数和时间值混用。
+- `v-model:playing` 和 `v-model:speed` 同步播放状态与倍速；`internalPlayback` 控制是否由组件内部推进播放，外部驱动时应用需要自行更新索引。
+- `pageSize` 控制展示分页，`loop` 控制循环；`showScale`、`showCurrentMarker` 控制刻度及当前时间标记。
+- 明确提供 `timeZone` 和带时区的时间字符串，例如 `2026-10-08T08:00:00+08:00`，避免使用含义依赖设备时区的字符串。
+- 提供 `date-select` 插槽，参数为 start-time、active-point、active-index、value、set-start-time 和 jump-to-time，可接入自定义日期选择器。组件不负责接口请求、缓存或地图渲染。
+
+## ProjectMenu
+
+`direction` 为 horizontal 或 vertical。横向布局读取 `items`，纵向布局读取 `groups`，切换 direction 时需要提供对应数据。`items` 为 `{ key, label, disabled?, icon? }[]`，`groups` 为 `{ label, items }[]`。具体布局示例见 AI-GUIDE。
+
+- `v-model:active` 同步选中 key；`select` 返回完整菜单项。
+- `disabled` 禁止选择；纵向菜单的 `icon` 接收 Vue 图标组件，不是图标名称字符串。横向菜单当前只显示文字。
+- 路由跳转、权限控制由应用在 select 中处理；分组折叠由组件内部处理。
+
+## MapSideMenu
+
+提供一个分类标题及其子菜单，支持按 label 搜索、分类展开和纯图标模式。`items` 为 `{ key, label, icon? }[]`，不具有 ProjectMenu 的 disabled 字段。
+
+- `v-model:active` 同步选中 key，`select` 返回菜单项。
+- `v-model:compact` 同步纯图标状态，`dark` 控制暗色外观。
+- 搜索和分类展开属于内部状态，没有相应的公开双向绑定。
+- 容器应提供明确高度，组件本身使用 height: 100%。切换图层和路由由应用处理。
+
+## MapTools
+
+工具 key 固定为 layers、module、refresh、locate、settings、analysis、context。`horizontal` 切换横向排列；`icons` 按 key 覆盖图标，值为 Vue 组件。
+
+- 点击任意工具均触发 `tool-click(key)`。
+- layers、module、settings、analysis 切换 active；再次点击当前项会取消选中并返回空字符串。
+- refresh、locate 触发动作，不修改 active。
+- context 使用独立内部状态，触发 `context-change(enabled)`；没有 `v-model:context`。
+- 组件仅提供按钮交互。地图定位、刷新、图层面板与空间分析由应用通过事件实现。
+
+## AtlasMapTitle
+
+`title` 必填；`subtitle` 默认空字符串，`rightOpen` 默认 false。
+
+标题使用绝对定位，建议父容器设置 `position: relative`。`rightOpen` 调整标题右侧留白，宽度使用主题变量 `--userssite-rightpanel-width`；应与应用右面板宽度一致。标题使用 pointer-events: none，没有点击事件或插槽。
+
+## AtlasRightToggleButton
+
+`open` 表示外部面板状态；点击触发无参数 `toggle`，组件不自行更新 open。`openTitle`、`closeTitle` 同时用于按钮标题和 aria-label。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { AtlasRightToggleButton } from 'sky-ui-kit'
+const open = ref(false)
+</script>
+<template>
+  <AtlasRightToggleButton :open="open" @toggle="open = !open" />
+  <aside v-if="open">面板内容</aside>
+</template>
+```
+
+## ProcessDataTable
+
+`times: string[]` 和 `series: { name: string; data: (number | null)[] }[]` 必填。第 i 个时间对应每个 series.data[i]；调用方应按相同时间顺序对齐数据。
+
+- `loading` 显示“查询中…”；times 为空显示“暂无数据”。
+- null 或缺失值显示“—”，0 仍显示为 0。
+- 内部每页固定 100 条，替换 times 数组时重置到首页。
+- 当前没有 pageSize、分页事件、排序、单元格插槽或远程分页 API。需要这些能力时使用 UiTable 组合实现。
+
+## 网站组件页还需要补充的内容
+
+当前指南补齐说明层，后续网站每个组件页面应把以下信息放在对应演示旁边：
+
+1. 中文用途及组件选择建议。
+2. 独立可复制示例，覆盖基础用法、受控状态和实际支持的边界状态。
+3. 带中文语义说明的 Props、Events、Slots 表；如有公开实例方法，再列 Exposes。
+4. 数据结构、事件载荷示例、样式变量与容器要求。
+5. 已验证的键盘交互、暗色与浮层行为；未验证内容不要标记为支持。
+6. 版本变更和已知限制，区分已导出组件、预览示例与尚未迁入的业务组件。
+
+Ui 基础组件已统一关联对应 Element Plus 主组件文档，例如 TableColumn 对应 Table 页面、FormItem 对应 Form 页面。完整组件、子组件、服务和指令清单见 [ELEMENT-PLUS-COVERAGE](ELEMENT-PLUS-COVERAGE.md)。独立示例与视觉状态仍需逐项补充和验证。
+
+
+MapSideMenu 支持 multiple 与 v-model:active-keys 多选，change 返回完整选中数组；select 表示点击项，不代表始终为新增选择。