sky-ui-kit 组件与样式库

安装版本选择（必须执行）

• 用户明确指定版本时，遵循该版本并核对能力；不擅自替换。
• 新项目未指定版本时，先执行 npm view sky-ui-kit dist-tags.latest 查询 npm 最新正式版，再执行 npm install sky-ui-kit@latest。不得从文档示例、历史记录、AI记忆或模板里的版本号推断本次安装版本；查询失败须说明，不能声称旧示例版本是最新版。
• 已有项目先读取 package.json、锁文件与已安装版本，检查兼容约束；“引入包”不等于授权无条件升级已有依赖。已有版本满足需求时沿用，确需升级时说明原因和影响，遵守项目约定。
• 复制包内起步模板时，新项目也应按上述规则解析版本，再按该版本的包内文档核对API。模板的依赖范围和文档最低支持版本是兼容信息，不是永久固定的安装指令。
• 安装后报告实际版本，由 package-lock.json 记录确切解析结果并保留锁文件。不要为“获取最新”删除锁文件，也不要写无约束的 * 依赖。将该规则合并至消费项目 AGENTS.md。

AI 接入入口：先询问用户

创建 Vue 项目时还需询问地图一张图、系统管理或组合模板，见 Vue 起步模板；用户未选择时不得自行生成其他业务工作台。

当用户要求引入 sky-ui-kit 时，必须先读取引导式接入流程，先询问用户接入 HTML/JavaScript 还是 Vue，再询问页面范围及接入目标，等待回答后配置。不得仅根据项目文件猜测路线；用户在当前对话已经明确的答案不重复询问。HTML 换肤保留原 DOM、业务事件和表单，不要求 Vue。按所选路线读取后续指南并合并项目 AGENTS.md；不能以安装成功或 CSS 已加载代替视觉及行为验收。

HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。

组件用途、数据约定、事件语义和限制见 组件使用说明；完整类型与默认值见 组件 API。

基于 Element Plus 二次封装，以原项目主题形成统一的 Vue 3 组件与样式库，并提供独立预览网站。标准层按 Element Plus 2.14.7 整理完整组件、服务与指令；项目特色层保留原有菜单、选择器、时间轴和地图组件。完整目录见 ELEMENT-PLUS-COVERAGE.md。出口与 API 索引覆盖不等于全部独立示例及交互状态均已完成验证。

组件库分类、统一出口和兼容规则见 COMPONENT-LIBRARY.md。基础组件使用 Ui 前缀，直接复用 Element Plus API；项目层保留现有组件名。两层共享项目主题。

发布后反向对接以 INTEGRATION.md 为准；逐页依赖见 PAGE-INVENTORY.md，全部原组件清单见 COMPONENT-INVENTORY.md。完整静态扫描数据保存在 docs/project-audit.json，可用 node scripts/audit-project.mjs 更新。扫描覆盖不代表全部业务组件已经迁入包。

全部原组件调用依据见 LEGACY-USAGE.md。包内已导出的 11 个项目组件均有预览和接入示例；标准组件独立示例逐模块完善。业务组件的调用片段保留原页面上下文，不能当作独立可运行示例。

当前实际使用清单见 COMPONENT-USAGE.md，逐模块替换、图标 Vite 配置、路由/地图薄适配、主题与验证方案见 ADAPTATION.md。图标页面与 AI 文档共用 src/icon-setup-examples.ts。更新参考项目后在库目录运行 node scripts/audit-project.mjs "D:\Work\01-项目code\一体化平台\webv1" 与 node scripts/scan-component-usage.mjs "D:\Work\01-项目code\一体化平台\webv1"，再生成 AI 文档；这些脚本只读取原项目。

库维护者本地运行

cd <组件库检出目录>
npm install
npm run dev

打开 http://127.0.0.1:5180 。支持明暗切换、六色调色板编辑、字号 / 圆角 / 控件高度 / 阴影调整、浏览器保存、JSON 导入导出。鼠标悬浮、键盘聚焦、输入校验、选择器浮层、日期选择器、弹窗及抽屉可直接核对。

提取范围与差异

• src/styles/theme.css：原项目根变量与暗色变量的快照。
• src/styles/vfit-vars.scss：原项目尺寸变量，默认缩放比例 1，不依赖 VFit 运行时。
• src/stores/theme.ts：保留原主题状态、默认值、迁移及 CSS 派生逻辑；预览站继续保留原浏览器存储键 userssite-element-plus-theme，不影响组件包名称。
• src/styles/element-plus.css：新增的 Element Plus 状态适配层，包含主色梯度、禁用、浮层和共享成功 / 警告语义色。这部分需要重点核对。
• src/styles/site.css：仅预览站布局，不进入 npm 样式包。
• 不包含地图样式规则、业务数据色带、业务页面局部样式、全局 body 重置或字体二进制。HarmonyOS Sans SC 可由使用方自行加载，否则使用系统中文字体回退。

原项目文件不随预览站修改；当前目录是独立快照，后续主题修订在此目录进行。默认 style.css 使用局部主题作用域，应在 Element Plus CSS 之后加载；只有主动整站换肤时才引入 global.css。

项目原生组件

预览站的「项目原生组件」直接使用原项目 src/components/common 中的 AppSelect、TreeSelectPanel、MapTimeline 和 TimeRangeQuickSelect。保留原有注释、局部 CSS、下拉浮层、动画及交互逻辑。独立包仅补充显式 Element Plus 导入和类型兼容修正；AppSelect 值类型补充多选数组。

MapTimeline 是项目中实况 / 预报分段时间轴；旧的 src/components/timeline/index.vue 小时时间轴尚未迁入。当前树节点、站点和时间序列为静态示例，不连接原业务接口。

import 'element-plus/dist/index.css'
import 'sky-ui-kit/style.css'
import { AppSelect, TreeSelectPanel, MapTimeline, TimeRangeQuickSelect } from 'sky-ui-kit/components'

组件包额外需要 @element-plus/icons-vue 和 motion-v。组件 CSS 已合并到 style.css，包含 Vue scoped 样式。

菜单样式

地图工具样式

独立展示区提供竖向地图工具栏、横向排列和静态图层控制浮动面板。MapTools 提取原 MapToolbar.vue 的按钮样式，默认包含图层、模块操作、刷新、定位、地图设置、空间分析和右键菜单。通过 active 指定选中工具，通过 horizontal 展示横向排列；支持 v-model:active、tool-click 和 context-change 事件；使用方通过事件接入地图、GIS 或业务接口。组件从 sky-ui-kit/components 导出，CSS 合并到 style.css。

地图与普通菜单

新增 MapSideMenu 地图胶囊菜单，样式直接提取自原项目 SideMenuMap.vue，保留分类圆形图标、橙色标题、蓝色子项、选中状态、连接线、顶部搜索胶囊和纯图标状态。图标使用 Element Plus 图标，可通过菜单项的 icon 属性传入自定义 Vue 图标组件。属性为 title、active、dark、compact、items（key / label / icon）。支持菜单选择、搜索过滤、分类展开收起和图标模式切换；通过 v-model:active、v-model:compact 和 select 事件接入业务。

ProjectMenu 从原 Header 和 SideMenu 提取独立菜单样式，仅展示横向、纵向、默认、选中和禁用状态。

从 sky-ui-kit/components 导入 ProjectMenu。属性：direction（horizontal / vertical）、active、items（key / label / disabled）及 groups（label / items）。菜单支持选择和分组折叠，通过 v-model:active 和 select 事件接入业务，不包含平台整体结构。

接入其他项目

以下为 Vue 组件路线；原生 HTML 使用 HTML 接入指南，不需要 Element Plus CSS 或 Vue。Vue 路线无需导入 useThemeStore，也无需安装 Pinia，按顺序引入 Element Plus CSS 与库 CSS，项目已有的同名变量优先；未定义的变量采用库默认值。详细优先级及暗色规则见 CSS-THEME.md。

import 'element-plus/dist/index.css'
import 'sky-ui-kit/style.css'
import { UiButton, AppSelect } from 'sky-ui-kit'

默认暗色：在 html 添加 theme-dark 类。当前项目可以继续使用自己的主题 store。预览站调色面板的 store 仅用于站内演示，不导出到 npm 包。

检查与打包

npm run typecheck
npm run build
npm pack --dry-run

site-dist/ 是可部署的预览网站，dist/ 是 npm 库产物。npm 包包含 dist 库产物、包内 AI/API/迁移文档、HTML 示例及 README；不包含预览网站、主题 store 运行时或原业务代码。

当前发布状态与维护发布流程

当前发布版本为 0.1.14，package.json 未设置 private 限制。HTML 按需样式和数字增强入口从 0.1.10 提供；0.1.12 增加先询问 HTML/Vue 的引导式接入流程；0.1.11 包含相对链接修复、透明地图覆盖层及旧页面迁移文档和示例。已安装的 0.1.10 需升级后获得修订。

消费项目无需执行库构建或发布操作。维护者仅在明确获得发布授权后，更新版本、运行 npm run docs:ai、类型检查和构建，核对包内文件后再发布。prepack 会生成文档并构建，不应把它当成纯检查命令。早期未发布状态见 开发历史归档。

样式隔离

默认 style.css 只给库组件作用域设置样式，作用域之外的原生 Element Plus 不受库 CSS 覆盖。主动整站换肤才额外导入 global.css。浮层、局部变量和默认 teleported 差异见 CSS-THEME.md。开发验证页：样式隔离验证。

AI 文档

安装或升级 npm 最新正式版：npm install sky-ui-kit@latest。团队 AI 从 llms.txt 开始读取；模块变化见 AI-CHANGELOG.md。后续修改必须同步相关 AI 文档并运行 npm run docs:ai，开发约定见 AGENTS.md。快速开始页面与 AI 文档共用 src/quick-start-examples.ts。

包内提供 llms.txt、llms-full.txt、components.json 和 docs/AI-GUIDE.md、docs/COMPONENT-API.md。让 AI 工具读取 node_modules/sky-ui-kit/llms.txt 开始，再按链接读取详细 API。文档不会随 npm install 自动进入 AI 上下文。项目组件 API 根据源码生成，Ui 基础组件关联 Element Plus 官方 API 和类型声明。

早期 0.1.7 安装说明已移至 开发历史归档。

0.1.13 提供完整 Vue 起步项目：一张图、预报、系统设置。详见 模板说明，复制包内 examples/vue-starter 即可开始。