224 lines
12 KiB
Markdown
224 lines
12 KiB
Markdown
# Prompt：itab 风格“逻辑型交互”完整多端项目（Extension + Web + Mobile H5）架构与 UI 交互实现方案（SCSS）
|
||
> 技术栈：Vite + Vue3 + TypeScript + Pinia + SCSS
|
||
> 目标：交互完整、符合 itab 这类“逻辑型工作台”的使用习惯；UI/交互都能跑通（后端接口先 mock），支持插件 New Tab + Web 预览 + 移动端 H5。
|
||
> 风格：iOS 扁平化 + 轻拟物（圆角/阴影/磨砂）+ 丝滑动画
|
||
> 规范：统一样式放全局 SCSS，组件目录 `ComponentName/index.vue + index.scss`
|
||
> 补充：Icon/Widget 下方都有 label（单行省略，Icon 必须可重命名）
|
||
|
||
---
|
||
|
||
## 0) 你必须理解“符合 itab 的逻辑型交互”是什么意思（必须按此实现）
|
||
itab 类产品的核心不是“能拖就行”，而是**工作台逻辑**：用户进入新标签页后，第一时间完成“搜索/打开网站/查看信息/快速编辑”，交互必须满足：
|
||
1) **默认浏览模式是“可用态”**：点击即打开、滚动即查看；不会因为可拖拽导致误触。
|
||
2) **编辑模式是“布局态”**：所有拖拽、尺寸、删除、批量操作只发生在编辑模式，且有明显工具条与控件。
|
||
3) **行为一致**：空白处/元素处右键菜单内容合理分层；同一入口在桌面与移动端有等价替代（右键=长按）。
|
||
4) **轻干扰但明确反馈**：toast、状态条、占位符、落位动画都要“轻”，不要吓人但要清晰。
|
||
5) **数据先本地后同步**：首屏永远本地秒开；同步/登录只影响“增强能力”，不阻断使用。
|
||
6) **组件是“卡片 + label”**：label 是信息结构的一部分（命名/识别），不是装饰；重命名入口必须自然（右键/设置/编辑态）。
|
||
|
||
---
|
||
|
||
## 强约束（必须遵守）
|
||
1) 三端同源代码：Web/Extension/Mobile H5 共用同一套 Vue3 + Pinia 业务代码；通过 build target/adapter 区分环境。
|
||
2) Web 可直接预览：无需插件即可体验完整 UI/交互。
|
||
3) Pinia 必须作为核心状态管理：避免 props 风暴。业务状态/交互状态/弹窗菜单状态必须进 store。
|
||
4) 禁止第三方拖拽/网格库：不得使用 react-grid-layout、gridstack、interact.js；网格拖拽必须原生：Pointer Events + rAF + transform + 自研 push-down/compact。
|
||
5) 仅鼠标/触控交互：不需要键盘辅助。
|
||
6) 元素规则固定：
|
||
- Icon：固定 `1×1`，可移动/编辑/删除/锁定；不可缩放。
|
||
- Widget：尺寸只能切换：`1×1, 1×2, 2×1, 2×2, 2×4`（离散）。
|
||
7) 每个元素都有 label：单行省略；Icon 必须支持重命名（Widget 可选）。
|
||
8) 组件封装目录强制：`ComponentName/index.vue + index.scss`。
|
||
9) 统一样式：全局 SCSS（`global.scss`）集中 token，组件局部 SCSS 只能引用 token。
|
||
10) 丝滑动画：必须给出统一动效体系，所有交互动效使用同一套 motion token。
|
||
|
||
---
|
||
|
||
# 你需要输出的 Markdown 文档结构（必须严格按顺序）
|
||
|
||
## 1. 产品与交互总览（itab 逻辑型）
|
||
- 用户进入新标签页的 3 个主任务路径（例如：搜索→打开；快速访问→打开；查看组件→轻操作）
|
||
- “浏览模式/编辑模式”的设计原则与对用户心智的解释
|
||
- 一致性原则：桌面/移动端等价交互映射（右键=长按）
|
||
|
||
## 2. 信息架构 IA（页面/面板/弹窗/菜单：必须完整）
|
||
必须列出所有入口并写：
|
||
- 触发方式（按钮/右键/长按/侧边栏）
|
||
- 承载容器（面板/弹窗/抽屉/路由页）
|
||
- 关闭方式（点击遮罩、返回、关闭按钮）
|
||
- 与主页面的关系（是否阻断、是否保留状态）
|
||
|
||
至少包含：
|
||
- 主页面（搜索栏 + 网格 + 侧边栏）
|
||
- 侧边栏面板：账号、组件库、设置、主题/壁纸、同步中心、帮助/关于
|
||
- 弹窗：登录、添加/编辑 Icon、Widget 设置、导入导出、确认删除
|
||
- 菜单：空白右键、Icon 右键、Widget 右键（移动端长按 ActionSheet）
|
||
- Onboarding 新手引导（首次进入）
|
||
|
||
## 3. 关键交互规范（必须写到“照着就能实现”，并符合 itab 逻辑）
|
||
### 3.1 浏览模式（默认态）
|
||
必须定义：
|
||
- 点击 Icon：打开链接（新标签/当前标签策略写清，可在设置里切换）
|
||
- 点击 Widget：进入 widget 的“轻交互”（如滚动、按钮刷新、查看详情）；不触发拖拽
|
||
- 点击 label：默认与点击卡片一致（或只选中，不打开——你必须选一个并解释为啥更像 itab）
|
||
- hover/pressed 反馈：阴影、缩放、光泽（轻拟物）
|
||
- 空白处点击：取消选中、关闭菜单
|
||
|
||
### 3.2 编辑模式（布局态）
|
||
必须定义：
|
||
- 进入/退出入口（顶部工具条/侧边栏开关/右键菜单）
|
||
- 编辑模式视觉：
|
||
- 网格底纹
|
||
- 卡片工具按钮（锁定/删除/设置/尺寸）
|
||
- 选中态描边
|
||
- 编辑模式操作：
|
||
- 拖拽移动（只允许从手柄触发，label 不触发拖拽）
|
||
- Widget 尺寸切换（五档 size picker）
|
||
- 多元素管理（至少支持：批量删除 或 批量锁定 任选其一；若不做必须说明原因）
|
||
- 编辑模式退出后：自动保存布局，toast 提示（轻提示）
|
||
|
||
### 3.3 右键菜单（itab 逻辑：层级清晰、动作合理）
|
||
必须分别定义：
|
||
1) 空白处右键菜单
|
||
2) Icon 右键菜单
|
||
3) Widget 右键菜单
|
||
对每一项写：名称/图标/动作/是否二级菜单/是否需要确认。
|
||
|
||
必须包含与 itab 逻辑一致的动作集合（可微调但要齐全）：
|
||
- 空白：添加 Icon、添加 Widget、进入/退出编辑模式、主题/壁纸、布局设置（compact/网格密度）、导入导出、同步中心、帮助/关于
|
||
- Icon：打开、在新标签打开（或设置项控制）、编辑（含重命名）、更换图标、复制链接、删除、锁定/解锁
|
||
- Widget：刷新、设置、尺寸（五档二级菜单）、复制配置（mock）、删除、锁定/解锁
|
||
|
||
移动端替代：
|
||
- 长按空白/元素 → ActionSheet（同菜单项结构）
|
||
|
||
### 3.4 侧边栏（工作台逻辑：主入口集合）
|
||
必须定义：
|
||
- 桌面侧边栏开合（overlay + 磨砂背景）
|
||
- 分区：账号区（头像/登录态）、快捷区（编辑/同步/主题）、面板区（组件库/设置/主题/同步）
|
||
- 面板切换动效与状态保留（切换后保留滚动位置与筛选条件）
|
||
- 与编辑模式联动：进入编辑模式时自动打开“组件库/布局设置”面板（或保持上次面板——你必须选一个并解释）
|
||
|
||
移动端：
|
||
- 侧边栏替代形态（建议全屏面板或底部抽屉），写清返回逻辑与层级管理
|
||
|
||
### 3.5 Label（逻辑型识别与管理）
|
||
必须定义：
|
||
- label 视觉：单行省略、对齐、间距（使用全局 label token）
|
||
- label 的交互：
|
||
- 浏览模式：点击 label 的行为（与卡片一致 or 仅选中）
|
||
- 编辑模式：label 不触发拖拽；重命名入口（至少 Icon）
|
||
- label 与布局关系：
|
||
- 网格占用只算卡片（w×h），label 是视觉附属
|
||
- 像素渲染要加固定 labelHeight，避免视觉重叠（写公式）
|
||
|
||
---
|
||
|
||
## 4. 工程架构（Vite + Vue3 + TS + Pinia，多端同源）
|
||
### 4.1 Monorepo 目录结构（必须可落地）
|
||
给出目录树并解释职责，要求包含：
|
||
- apps/web、apps/extension、apps/mobile（可选）
|
||
- packages/core、ui、engine、widgets、shared
|
||
- 每个模块的职责边界与依赖方向（禁止环依赖）
|
||
|
||
### 4.2 组件文件组织（必须符合你的封装规范）
|
||
- 每个组件一个文件夹：`ComponentName/index.vue` + `index.scss`
|
||
- UI 基础组件与业务组件放置规则
|
||
- 示例：Sidebar/ContextMenu/GridCanvas/IconTile/WidgetCard/Label
|
||
|
||
---
|
||
|
||
## 5. Pinia 设计（避免 props 风暴，必须非常具体）
|
||
### 5.1 Store 拆分与字段（必须给清单）
|
||
至少包含：
|
||
- useLayoutStore：items、layoutsByBreakpoint、editMode、selectedId、dragState、compactEnabled、gridConfig
|
||
- useUIStore：sidebarOpen、activePanel、dialogs、toasts、contextMenuState、actionSheetState（移动端）、overlayStack
|
||
- useAuthStore：user、token(mock)、status
|
||
- useSettingsStore：theme、wallpaper、searchEngine、openLinkBehavior、gridDensity、motionLevel（可选）
|
||
- useWidgetsStore：registry、instances、schemas、mockData
|
||
- useSyncStore：syncState(mock)、lastSyncAt、conflictFlag
|
||
- useOnboardingStore：hasSeen、steps、currentStep
|
||
|
||
必须写：
|
||
- 哪些组件只通过 store 取数据（容器组件）
|
||
- 哪些组件允许 props（纯展示）
|
||
- 如何避免 store 间耦合：通过 services/adapters 作为协调层
|
||
|
||
---
|
||
|
||
## 6. UI 风格与全局 SCSS（必须能“一处改全局”）
|
||
### 6.1 global.scss 结构与 tokens（必须详细）
|
||
- tokens.scss：SCSS 变量 + :root CSS variables 映射（推荐双层）
|
||
- reset/base/utilities/components
|
||
- 必须列出 token 分类与命名规则（颜色/圆角/阴影/动效/间距/层级/label）
|
||
|
||
### 6.2 通用组件样式（必须给示例）
|
||
- Card、Button、Menu、Drawer、Modal、Toast、Label 的通用 class 示例（引用 token）
|
||
- pressed/hover 状态的阴影与轻缩放
|
||
- 磨砂背景 class（带降级）
|
||
|
||
---
|
||
|
||
## 7. 动效体系（必须体现“丝滑”与一致性）
|
||
- motion token：duration/easing
|
||
- 菜单/抽屉/弹窗/落位动画统一规则
|
||
- 拖拽落位动画：松手后卡片过渡到最终位置（transform 过渡）
|
||
- 避免卡顿策略：只动 transform/opacity/box-shadow
|
||
|
||
---
|
||
|
||
## 8. 网格布局引擎（原生算法，必须给伪代码）
|
||
必须包含并解释：
|
||
- collides(a,b)
|
||
- clampRect(rect, cols)
|
||
- resolvePushDown(target, items, cols)：队列迭代 + 固定排序 + icon 优先被推挤
|
||
- compactIcons(items, cols)：icon-only compact（可配置）
|
||
- findFirstFit(size, items, cols, startY)
|
||
并写清：
|
||
- 拖动中：transform + placeholder
|
||
- 松手 commit：resolve + compact + save + 落位动画
|
||
- labelHeight 的像素渲染处理公式
|
||
|
||
---
|
||
|
||
## 9. Mock 与持久化（IndexedDB）
|
||
- 表：layout/settings/user/widgetsData/onboarding
|
||
- 迁移：version + migrations
|
||
- mock 登录、mock 同步、mock widget 刷新、模拟网络失败开关
|
||
- 导入导出 JSON（包含 label）
|
||
|
||
---
|
||
|
||
## 10. 逐功能实现清单（必须覆盖 itab 常见功能）
|
||
用“功能 → UI 入口 → 交互流程 → store 字段变化 → 组件列表”形式写清：
|
||
- 搜索（引擎切换、输入框动效、建议 mock）
|
||
- Icon 管理（添加/编辑/重命名/更换图标/删除/锁定）
|
||
- Widget 管理（添加/设置/刷新/尺寸切换/删除/锁定）
|
||
- 主题/壁纸（选择、预览、应用、随机切换 mock）
|
||
- 设置（布局设置、打开链接行为、动效强度、隐私）
|
||
- 同步中心（mock）
|
||
- Onboarding 引导（高亮与遮罩）
|
||
- Toast/错误态/空态
|
||
|
||
---
|
||
|
||
## 11. 验收标准（至少 35 条，必须体现“符合 itab 逻辑型交互”）
|
||
必须覆盖：
|
||
- 默认浏览模式不误触拖拽，点击即打开/查看
|
||
- 编辑模式才可拖拽与改尺寸，退出自动保存
|
||
- 右键菜单/长按菜单结构合理、定位正确、动效顺滑
|
||
- 侧边栏作为“主入口集合”逻辑清晰
|
||
- label 显示与重命名流程自然（至少 Icon）
|
||
- 全局 SCSS 改 token 可全局换肤（圆角/阴影/颜色/动效）
|
||
- Web 可预览、Extension 可运行、H5 交互等价（右键=长按）
|
||
- 性能：TTI、拖拽帧率、commit 耗时可观测（本地开发面板）
|
||
|
||
---
|
||
|
||
## 输出要求（必须）
|
||
- 输出必须是 Markdown
|
||
- 不要空话：给参数（cols/rowHeight/gap/snap阈值/labelHeight/动画时长）
|
||
- Pinia 设计要清晰，避免 props 风暴
|
||
- 拖拽网格必须自研原生算法
|
||
- 登录/同步/刷新均 mock，但 UI/交互要完整可实现
|