@qilitt-mickey/vue3-temp-skill 1.1.76 → 1.2.2

package/references/adapters/vue-antdv.md

@@ -0,0 +1,110 @@
+---
+adapter: vue-antdv
+description: Vue 3 + Ant Design Vue 适配。提供深度选择器语法、组件库穿透前缀、三份 CSS 的落点与引入方式。
+---
+
+# adapter · Vue 3 + Ant Design Vue
+
+## 深度选择器语法
+
+| 场景 | 语法 |
+|---|---|
+| SFC `<style scoped>` | `:deep(.ant-xxx)` |
+| 全局样式文件（非 scoped） | `.ant-xxx` 直接写 |
+
+`ui-roles.css` 写成**全局样式文件**（不 scoped）。
+
+## 内层穿透语法
+
+| 角色 | 穿透目标 |
+|---|---|
+| `table.headerCell` | `:deep(.ant-table-cell)` |
+| `table.cell` | `:deep(.ant-table-cell)` |
+| `filter.input` | `:deep(.ant-input)` / `:deep(input)` |
+| `shell.sidebar.item` | `:deep(.ant-menu-title-content)` |
+| `tag.status` | 根元素即可 |
+
+**规则**：`host[]` 挂组件根元素；`inner[]` 穿透到内部文本盒——目标由组件库 DOM 结构决定。
+
+## 组件库前缀速查
+
+| 组件 | 前缀 | 角色类挂载位置 |
+|---|---|---|
+| Button | `.ant-btn` | 根元素 |
+| Input | `.ant-input` / `.ant-input-affix-wrapper` | 根元素 / wrapper |
+| Select | `.ant-select` | `.ant-select-selector` |
+| Table | `.ant-table` | 根元素 |
+| Table Cell | `.ant-table-cell` | `th` / `td` |
+| Tag | `.ant-tag` | 根元素 |
+| Pagination | `.ant-pagination` | 根元素 |
+| Card | `.ant-card` | `.ant-card-body`（内边距在 body） |
+| Modal | `.ant-modal` | `.ant-modal-content` |
+| Menu | `.ant-menu` | `.ant-menu-item` |
+| Tabs | `.ant-tabs` | `.ant-tabs-tab` |
+| DatePicker | `.ant-picker` | `.ant-picker-input input` |
+| Form | `.ant-form` | `.ant-form-item` |
+
+## 角色类挂载方式（视觉不生效的头号原因）
+
+**CSS 生成了不等于视觉会变**——必须把角色类挂到组件上。
+
+| 契约角色 | 挂载写法 |
+|---|---|
+| `button.*` | `<a-button :class="[...]">` |
+| `shell.sidebar.item` | `<a-menu-item :class="[...]">` |
+| `shell.tabs.item` | `<a-tab-pane :class="[...]">` |
+| `input.base` / `filter.input` | `<a-input :class="[...]">`，`inner` 用 `:deep(.ant-input)` |
+| `select.base` | `<a-select :class="[...]">`，`inner` 用 `:deep(.ant-select-selector)` |
+| `filter.dateRange` | `<a-range-picker :class="[...]">` |
+| `tag.status` | `<a-tag :class="[...]">` |
+| `card.base` | `<a-card :class="[...]">`，`inner` 用 `:deep(.ant-card-body)` |
+| `table.wrapper` | `<a-table :class="[...]">` |
+| `table.headerCell` / `table.cell` | **用 `#headerCell` / `#bodyCell` 插槽**：`#bodyCell="{ column, record }"` 内给单元格外层元素加类 |
+| `table.cell.amount` | 同上 + `align: 'right'` |
+| `pagination.bar` | `<a-pagination :class="[...]">` |
+
+**Table 的特殊性**：`a-table` 的单元格同样由组件内部生成。推荐用 `#bodyCell` 插槽批量挂载：
+
+```vue
+<a-table :data-source="rows" :columns="columns" class="role-table-wrapper">
+  <template #headerCell="{ column }">
+    <div :class="column.dataIndex === 'name' ? 'role-table-header-cell' : 'role-table-header-cell'">
+      {{ column.title }}
+    </div>
+  </template>
+  <template #bodyCell="{ column, record }">
+    <div :class="cellRole(column, record)">{{ record[column.dataIndex] }}</div>
+  </template>
+</a-table>
+```
+
+### 批量挂载的做法
+
+一个页面有 20+ 角色时**逐个手写 class 会漏**。做法：把契约角色名转成类名清单，交给页面统一挂载，并在第 0 步自检里确认覆盖率 100%。
+
+**类名转换规则**：`table.headerCell` → `.role-table-header-cell`（点号与驼峰都转小写连字符）。
+
+## 提权通道（唯一允许处）
+
+| 情况 | 处置 |
+|---|---|
+| 组件库用行内 style 注入 | 该属性上加 `!important`——**仅此一处允许** |
+| 组件库 `!important` 覆盖角色类 | 同上 |
+
+**只加在具体属性上，不整条加。**
+
+## 三份 CSS 的落点
+
+| 文件 | 落点 | 引入时机 |
+|---|---|---|
+| `src/styles/ui-tokens.css` | 项目样式目录 | 样式入口全局引入一次 |
+| `src/styles/ui-roles.css` | 项目样式目录 | 同上，必须是全局文件 |
+| `src/styles/ui-layout.css` | 项目样式目录 | 同上 |
+
+## 布局占位容器
+
+布局组件退化为占位容器（只提供插槽，不参与布局决策），结构同 Element Plus 的写法。
+
+## 与 Element Plus 的差异
+
+Ant Design Vue 的 `card` 内边距在 `.ant-card-body`（Element Plus 在根元素），`table` 单元格文本盒是 `.ant-table-cell` 本身（Element Plus 有额外 `.cell` 层）。**这是唯一需要在 adapter 里区分的地方**——契约本身不变。

package/references/adapters/vue-element-plus.md

@@ -0,0 +1,132 @@
+---
+adapter: vue-element-plus
+description: Vue 3 + Element Plus 适配。提供深度选择器语法、组件库穿透前缀、三份 CSS 的落点与引入方式。
+---
+
+# adapter · Vue 3 + Element Plus
+
+## 深度选择器语法
+
+| 场景 | 语法 |
+|---|---|
+| SFC `<style scoped>` | `:deep(.el-xxx)` |
+| 全局样式文件（非 scoped） | `.el-xxx` 直接写，不需要穿透 |
+| SCSS | 同上 |
+
+**本项目建议**：`ui-roles.css` 写成**全局样式文件**（不 scoped），避免每个页面重复引入。
+
+## 内层穿透语法
+
+契约的 `inner[]` 落到组件内部文本盒时，需要穿透到组件库内部元素：
+
+| 角色 | 穿透目标 |
+|---|---|
+| `table.headerCell` | `:deep(.cell)` |
+| `table.cell` | `:deep(.cell)` |
+| `shell.sidebar.item` | `:deep(span)` |
+| `filter.input` | `:deep(input)` |
+| `shell.tabs.item` | 直接作用在文本节点（无需穿透） |
+
+**规则**：`host[]` 作用在组件根元素（加角色类即可）；`inner[]` 作用在根元素内部——**用 adapter 给出的穿透目标定位**。目标选择器由组件库 DOM 结构决定，不由契约决定。
+
+## 组件库前缀速查
+
+| 组件 | 前缀 | 角色类挂载位置 |
+|---|---|---|
+| Button | `.el-button` | 组件根元素 |
+| Input | `.el-input` | `.el-input__wrapper` 或根元素 |
+| Select | `.el-select` | `.el-select__wrapper` |
+| Table | `.el-table` | 根元素 |
+| Table Header Cell | `.el-table__cell` | `.th.el-table__cell`（`th` 上的 `.cell` 是内层） |
+| Table Cell | `.el-table__cell` | `td.el-table__cell` |
+| Tag | `.el-tag` | 根元素 |
+| Pagination | `.el-pagination` | 根元素 |
+| Card | `.el-card` | `.el-card__body`（内边距在 body 上） |
+| Dialog | `.el-dialog` | `.el-dialog__body` |
+| Menu | `.el-menu` | `.el-menu-item` |
+| Tabs | `.el-tabs` | `.el-tabs__item` |
+| DatePicker | `.el-date-editor` | `.el-range-input` |
+
+## 角色类挂载方式（视觉不生效的头号原因）
+
+**CSS 生成了不等于视觉会变**——必须把角色类挂到组件上。Element Plus 各组件的挂法不同：
+
+| 契约角色 | 挂载写法 | 说明 |
+|---|---|---|
+| `shell.sidebar.item` / `.active` | `<el-menu-item :class="[...]">` | 直接作用在组件根元素 |
+| `shell.header.icon` | `<el-button :class="[...]">` | 同上 |
+| `button.primary` / `.secondary` / `.danger` | `<el-button :class="[...]">` | 同上 |
+| `card.base` | `<el-card :class="[...]">` | 内边距在 `.el-card__body`，`host` 作用在根、`inner` 用 `:deep(.el-card__body)` |
+| `table.wrapper` | `<el-table :class="[...]">` | 表格**根元素**挂 wrapper |
+| `table.headerCell` | **需走插槽**：`<template #header><th class="role-table-header-cell">` | Element Plus 的 `th` 不能直接加类 |
+| `table.cell` | `<el-table-column :class="[...]">` 或插槽内 `td` | 列组件加类 |
+| `table.cell.amount` | 同上 + `:deep(.cell)` 承接 `inner` | 右对齐靠 `text-align` |
+| `tag.status` | `<el-tag :class="[...]">` | 直接作用 |
+| `input.base` / `filter.input` | `<el-input :class="[...]">` | `inner` 用 `:deep(.el-input__wrapper)` 或 `:deep(input)` |
+| `select.base` | `<el-select :class="[...]">` | `inner` 用 `:deep(.el-select__wrapper)` |
+| `filter.dateRange` | `<el-date-picker :class="[...]">` | — |
+| `pagination.bar` | `<el-pagination :class="[...]">` | 直接作用 |
+| `shell.tabs.item` | 自绘或 `<el-tab-pane>` | 激活态另由 `item.active` 角色承载 |
+
+**Table 的特殊性**：`el-table` 的 `th` / `td` 由组件内部生成，**不能直接在 `<el-table>` 上加类来影响单元格**。表头必须用 `#header` 插槽自绘：
+
+```vue
+<el-table :data="rows" class="role-table-wrapper">
+  <template #header>
+    <div class="role-table-header-cell">运单号</div>
+  </template>
+  <el-table-column prop="name" label="名称" class="role-table-cell" />
+  <el-table-column prop="fee"  label="运费" class="role-table-cell-amount" />
+  <template #default="{ row }">
+    <el-tag class="role-tag-status">{{ row.status }}</el-tag>
+  </template>
+</el-table>
+```
+
+### 批量挂载的做法
+
+一个页面有 20+ 角色时**逐个手写 class 会漏**。做法：把契约的角色名转成类名清单，交给页面统一挂载，并在第 0 步自检里确认覆盖率 100%。
+
+**类名转换规则**：`table.headerCell` → `.role-table-header-cell`（点号与驼峰都转小写连字符）。
+
+## 提权通道（唯一允许处）
+
+角色类是独立命名空间（`role-` 前缀）+ 独立文件，**通常不需要提权**。仅两种情况需要：
+
+| 情况 | 处置 |
+|---|---|
+| 组件库用行内 style 注入（如 `:header-cell-style`） | 在角色类上对该属性加 `!important`——**仅此一处允许** |
+| 组件库 `!important` 覆盖了角色类 | 同上 |
+
+**提权只加在具体属性上，不整条加**。整条加会让后续所有变体都带上高权重。
+
+## 三份 CSS 的落点
+
+| 文件 | 落点 | 引入时机 |
+|---|---|---|
+| `src/styles/ui-tokens.css` | 项目样式目录 | 样式入口全局引入一次 |
+| `src/styles/ui-roles.css` | 项目样式目录 | 同上，**必须是不 scoped 的全局文件** |
+| `src/styles/ui-layout.css` | 项目样式目录 | 同上 |
+
+## 布局占位容器
+
+项目的 `lay-admin` 等布局组件退化为占位容器：
+
+```vue
+<template>
+  <div class="ui-page">
+    <aside class="ui-region-sidebar"><slot name="sidebar" /></aside>
+    <header class="ui-region-header"><slot name="header" /></header>
+    <nav class="ui-region-tabs"><slot name="tabs" /></nav>
+    <main class="ui-region-content"><slot name="content" /></main>
+  </div>
+</template>
+```
+
+**布局组件只提供插槽，不参与布局决策**——网格由 `ui-layout.css` 决定。改造范围限定在布局组件的模板与样式层，不动业务代码。
+
+## 不做
+
+- 不改组件库源码
+- 不在业务页面写角色类以外的设计样式
+- 不把契约值硬编码进布局组件（布局取值来自 `ui-layout.css`）