@done-coding/admin-core 0.21.0 → 0.22.0

package/es/style.css

@@ -71,9 +71,30 @@
 .form-item-label-hide[data-v-8b508d64] .el-form-item__label-wrap {
   display: none;
 }
-[data-v-cc2ea388] .el-row > .el-col > .el-form-item {
+[data-v-fca51c0e] .el-row > .el-col > .el-form-item {
   margin-bottom: 18px;
 }
+.dc-form-shadow-clone-dispatch[data-v-5096627a] {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  color: var(--el-text-color-regular);
+}
+.dc-form-shadow-clone-dispatch__label[data-v-5096627a] {
+  font-size: 14px;
+  font-weight: 600;
+  white-space: nowrap;
+}
+.dc-form-shadow-clone-dispatch--active[data-v-5096627a] {
+  color: var(--dc-core-primary-color, var(--el-color-primary));
+}
+.dc-form-shadow-clone-dispatch--active .dc-form-filter-funnel[data-v-5096627a] {
+  color: inherit;
+}
+.dc-form-filter-funnel[data-v-5096627a] {
+  padding: 4px;
+  color: var(--el-text-color-secondary);
+}
 .form-submit-panel[data-v-1505775a] {
   display: flex;
   flex-direction: column;
@@ -520,27 +541,79 @@
 .app-theme__style-select[data-v-06ca4822] {
   width: 120px;
 }
-.app-layout[data-v-f6f87b30] {
+.modal-video-preview__stage[data-v-d4b84c07] {
+  height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--el-color-black);
+}
+.modal-video-preview__shim[data-v-d4b84c07] {
+  width: min(960px, 100%);
+  aspect-ratio: 16 / 9;
+}
+.modal-video-preview__video[data-v-d4b84c07] {
+  display: block;
+  width: 100%;
+  height: 100%;
+  background: var(--el-color-black);
+}
+.dc-modal-video-preview.el-dialog {
+  background: transparent;
+  box-shadow: none;
+  border: none;
+  border-radius: 0;
+  overflow: visible;
+  padding: 0;
+}
+.dc-modal-video-preview.el-dialog .el-dialog__header {
+  padding: 0;
+}
+.dc-modal-video-preview.el-dialog .el-dialog__body {
+  padding: 0;
+}
+.dc-modal-video-preview.el-dialog .el-dialog__headerbtn {
+  top: 40px;
+  right: 40px;
+  width: 44px;
+  height: 44px;
+  border-radius: 50%;
+  background: #606266;
+  color: var(--el-color-white);
+  opacity: 0.9;
+  transition: opacity 0.2s;
+}
+.dc-modal-video-preview.el-dialog .el-dialog__headerbtn:hover {
+  opacity: 1;
+}
+.dc-modal-video-preview.el-dialog .el-dialog__headerbtn .el-dialog__close {
+  color: inherit;
+  font-size: 24px;
+}
+.dc-modal-video-preview__overlay {
+  background: var(--el-overlay-color-dark, rgba(0, 0, 0, 0.7));
+}
+.app-layout[data-v-b45bcdfd] {
   position: relative;
 }
-.app-layout_noLogin[data-v-f6f87b30] .app-body,
-.app-layout_noLogin[data-v-f6f87b30] .app-sidebar,
-.app-layout_noLogin[data-v-f6f87b30] .app-header,
-.app-layout_noLogin[data-v-f6f87b30] .app-footer {
+.app-layout_noLogin[data-v-b45bcdfd] .app-body,
+.app-layout_noLogin[data-v-b45bcdfd] .app-sidebar,
+.app-layout_noLogin[data-v-b45bcdfd] .app-header,
+.app-layout_noLogin[data-v-b45bcdfd] .app-footer {
   transition: none !important;
 }
-.app-page[data-v-8fb8acc9] {
-  --dc-page-content-viewport-top: var(--v292949d5);
-  --dc-page-content-viewport-bottom: var(--v45d97caa);
-  --dc-page-content-viewport-left: var(--v0807b0f2);
-  --dc-page-content-viewport-right: var(--f841aac8);
-  --dc-page-content-viewport-width: var(--f7b4d374);
-  --dc-page-content-viewport-height: var(--v32838eb2);
+.app-page[data-v-2d4bb608] {
+  --dc-page-content-viewport-top: var(--v68a1d5b5);
+  --dc-page-content-viewport-bottom: var(--v0a30a9cb);
+  --dc-page-content-viewport-left: var(--a8d5d0b2);
+  --dc-page-content-viewport-right: var(--v71378308);
+  --dc-page-content-viewport-width: var(--v70aaabb4);
+  --dc-page-content-viewport-height: var(--v13dba0c7);
 }
-.app-page-shim[data-v-8fb8acc9] {
-  --app-viewport-max-height: var(--v5c736bbc);
+.app-page-shim[data-v-2d4bb608] {
+  --app-viewport-max-height: var(--v746c0602);
 }
-.app-page-slot-shim[data-v-8fb8acc9] {
+.app-page-slot-shim[data-v-2d4bb608] {
   box-sizing: border-box;
   width: 100%;
   height: 100%;
@@ -568,6 +641,26 @@ to {
     transform: rotate(360deg);
 }
 }
+.form-active-filter[data-v-6d2d37c2] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding-bottom: 4px;
+}
+.form-active-filter__label[data-v-6d2d37c2] {
+  font-weight: 600;
+}
+.form-active-filter__clear[data-v-6d2d37c2] {
+  margin-left: 4px;
+}
+.form-active-filter__empty[data-v-6d2d37c2] {
+  display: inline-flex;
+  align-items: center;
+  height: 24px;
+  font-size: 13px;
+  color: var(--el-text-color-placeholder);
+}
 .form-item-nest-form[data-v-a413a382] {
   padding: 16px;
   border: 1px solid var(--dc-core-border-color);
@@ -594,6 +687,292 @@ to {
   border-radius: 6px;
   box-shadow: var(--el-box-shadow-lighter);
 }
+.form-sort__chip[data-v-9aa4f615] {
+  position: relative;
+  align-self: flex-start;
+  margin-left: 0;
+  padding-left: 6px;
+  padding-right: 6px;
+  color: var(--el-text-color-regular);
+  background: var(--el-fill-color-blank);
+  border-color: var(--el-border-color);
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
+}
+.form-sort--cycle.form-sort__chip[data-v-9aa4f615]:hover {
+  color: var(--el-color-primary);
+  border-color: var(--el-color-primary-light-5);
+  background: var(--el-fill-color-light);
+}
+.form-sort__chip_active[data-v-9aa4f615] {
+  color: var(--el-color-primary);
+  background: var(--el-color-primary-light-9);
+  border-color: var(--el-color-primary-light-5);
+}
+.form-sort__icon[data-v-9aa4f615] {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 22px;
+  margin-right: 4px;
+}
+.form-sort__caret[data-v-9aa4f615] {
+  position: relative;
+  font-size: 12px;
+  line-height: 0.6;
+  color: var(--el-text-color-placeholder);
+}
+.form-sort__caret[data-v-9aa4f615]::before {
+  content: "";
+  position: absolute;
+  inset: -3px -5px;
+}
+.form-sort__caret[data-v-9aa4f615]:first-child {
+  margin-bottom: -2px;
+}
+.form-sort__caret[data-v-9aa4f615]:last-child {
+  margin-top: -2px;
+}
+.form-sort--dual-arrow.form-sort__chip[data-v-9aa4f615] {
+  cursor: default;
+}
+.form-sort--dual-arrow .form-sort__caret[data-v-9aa4f615] {
+  cursor: pointer;
+  color: var(--el-text-color-secondary);
+}
+.form-sort--dual-arrow .form-sort__caret[data-v-9aa4f615]:hover {
+  color: var(--el-color-primary);
+}
+.form-sort__caret_on[data-v-9aa4f615],
+.form-sort--dual-arrow .form-sort__caret_on[data-v-9aa4f615] {
+  color: var(--el-color-primary);
+}
+.form-sort__order[data-v-9aa4f615] {
+  margin-left: 6px;
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 1;
+  color: var(--el-color-primary);
+}
+.form-sort[data-v-e86178b8] {
+  display: inline-flex;
+  vertical-align: middle;
+}
+.dc-form-upload-trigger[data-v-9fb0fb2a] {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  padding: 14px 16px;
+  color: var(--el-text-color-secondary);
+  cursor: pointer;
+  transition: color 0.2s;
+}
+.dc-form-upload-trigger[data-v-9fb0fb2a]:hover {
+  color: var(--el-color-primary);
+}
+.dc-form-upload-trigger_card[data-v-9fb0fb2a] {
+  width: 100%;
+  height: 100%;
+  padding: 0;
+  color: var(--el-text-color-secondary);
+}
+.dc-form-upload__placeholder[data-v-158fc67d] {
+  margin-top: 4px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--el-text-color-secondary);
+}
+.dc-form-upload__inner {
+  display: flex;
+  flex-direction: column;
+}
+.dc-form-upload__inner > .el-upload-list {
+  order: 1;
+}
+.dc-form-upload__inner > .el-upload {
+  order: 2;
+}
+.dc-form-upload_full .el-upload {
+  display: none;
+}
+.dc-form-upload-file-info[data-v-6a6d170c] {
+  min-width: 0;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.dc-form-upload-file-info__name[data-v-6a6d170c] {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 13px;
+  color: var(--el-text-color-primary);
+}
+.dc-form-upload-file-info__meta[data-v-6a6d170c] {
+  font-size: 12px;
+  color: var(--el-text-color-secondary);
+}
+.dc-form-upload-audio__item[data-v-3884f0f6] {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+}
+.dc-form-upload-audio__player[data-v-3884f0f6] {
+  flex-shrink: 0;
+  width: 240px;
+  height: 32px;
+}
+.dc-form-upload-audio__player_empty[data-v-3884f0f6] {
+  background: var(--el-fill-color-light);
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
+}
+.dc-form-upload-audio__remove[data-v-3884f0f6] {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: var(--el-color-info-dark-2, #606266);
+  color: var(--el-color-white);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.2s;
+}
+.dc-form-upload-audio__item:hover .dc-form-upload-audio__remove[data-v-3884f0f6] {
+  opacity: 1;
+}
+.dc-form-upload-card[data-v-48323f64] {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: var(--el-fill-color-light);
+}
+.dc-form-upload-card__mask[data-v-48323f64] {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: 0 8px;
+  background: var(--el-overlay-color-lighter, rgba(0, 0, 0, 0.2));
+  color: var(--el-color-white);
+  font-size: 12px;
+}
+.dc-form-upload-card__mask-name[data-v-48323f64] {
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.dc-form-upload-card__mask-percent[data-v-48323f64] {
+  font-size: 13px;
+  font-weight: 600;
+}
+.dc-form-upload-card__mask-bar[data-v-48323f64] {
+  position: absolute;
+  left: 0;
+  bottom: 0;
+  height: 3px;
+  background: var(--el-color-primary);
+  transition: width 0.2s;
+}
+.dc-form-upload-card__remove[data-v-48323f64] {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: var(--el-color-info-dark-2, #606266);
+  color: var(--el-color-white);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.2s;
+}
+.dc-form-upload-card:hover .dc-form-upload-card__remove[data-v-48323f64] {
+  opacity: 1;
+}
+.dc-form-upload-image__thumb[data-v-9d62114a] {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+.dc-form-upload-image__thumb_empty[data-v-9d62114a] {
+  background: var(--el-fill-color-light);
+}
+.video-preview-trigger_placeholder[data-v-49e0acc8] {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  max-width: 360px;
+  background: var(--el-fill-color-dark);
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
+  cursor: pointer;
+  transition: background-color 0.2s;
+}
+.video-preview-trigger_placeholder[data-v-49e0acc8]:hover {
+  background: var(--el-fill-color-darker);
+}
+.video-preview-trigger_cover[data-v-49e0acc8] {
+  position: relative;
+  display: inline-block;
+  line-height: 0;
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
+  overflow: hidden;
+  cursor: pointer;
+}
+.video-preview-trigger_cover .video-preview-trigger__cover[data-v-49e0acc8] {
+  display: block;
+}
+.video-preview-trigger__play-badge[data-v-49e0acc8] {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 48px;
+  height: 48px;
+  border-radius: 50%;
+  background: var(--el-overlay-color-light, rgba(0, 0, 0, 0.35));
+  color: var(--el-color-white);
+  pointer-events: none;
+  transition: transform 0.2s;
+}
+.video-preview-trigger_cover:hover .video-preview-trigger__play-badge[data-v-49e0acc8] {
+  transform: translate(-50%, -50%) scale(1.08);
+}
+.video-preview-trigger__play-icon[data-v-49e0acc8] {
+  color: var(--dc-core-primary-color, var(--el-color-primary));
+}
+.dc-form-upload[data-v-5eac98bc] .video-preview-trigger_placeholder {
+  width: 100%;
+  height: 100%;
+  max-width: none;
+  border-radius: 0;
+}
+.dc-form-upload-video__thumb_empty[data-v-5eac98bc] {
+  background: var(--el-fill-color-light);
+}
 .table-toolbar[data-v-0220e327] {
   display: flex;
   justify-content: space-between;
@@ -692,13 +1071,13 @@ to {
   min-height: 60px;
   grid-column: 1 / -1;
 }
-.table-main-pagination[data-v-54ab0e8e] {
+.table-main-pagination[data-v-6a8d4637] {
   margin-top: 10px;
   display: flex;
   justify-content: flex-end;
 }
-.table-main_fill[data-v-54ab0e8e] .el-table__body-wrapper {
-  min-height: var(--v6df3e765);
+.table-main_fill[data-v-6a8d4637] .el-table__body-wrapper {
+  min-height: var(--ed56f300);
 }
 .dc-slot-layout-flow-aside_separate[data-v-5c6ef74b] {
   position: relative;
@@ -728,40 +1107,40 @@ to {
 .dc-slot-layout-flow-aside-main[data-v-5c6ef74b] {
   width: var(--v7e1d11ca);
 }
-.list-layout[data-v-5301293b] {
-  min-height: var(--ee852864);
+.list-layout[data-v-8527d1df] {
+  min-height: var(--v3483351c);
 }
-.list-layout-header[data-v-5301293b] {
+.list-layout-header[data-v-8527d1df] {
   margin-bottom: 10px;
 }
-.list-layout-operation[data-v-5301293b] {
+.list-layout-operation[data-v-8527d1df] {
   margin-bottom: 10px;
 }
-.list-layout_search-sticky[data-v-5301293b] .form-search {
+.list-layout_search-sticky[data-v-8527d1df] .form-search {
   position: sticky;
-  top: var(--v6179ebd9);
+  top: var(--v5ccbcb06);
   z-index: 10;
   background: var(--dc-core-surface, var(--el-bg-color));
   box-shadow: 0 1px 0 0 var(--dc-core-border-color, var(--el-border-color-lighter));
 }
-.list-layout_toolbar-sticky[data-v-5301293b] .dc-table-main__toolbar {
+.list-layout_toolbar-sticky[data-v-8527d1df] .dc-table-main__toolbar {
   position: sticky;
-  top: var(--v0e6603c8);
+  top: var(--e69ab810);
   z-index: 9;
   padding-top: 10px;
   background: var(--dc-core-surface, var(--el-bg-color));
   box-shadow: 0 1px 0 0 var(--dc-core-border-color, var(--el-border-color-lighter));
 }
-.list-layout_pager-sticky[data-v-5301293b] .dc-table-main__pagination {
+.list-layout_pager-sticky[data-v-8527d1df] .dc-table-main__pagination {
   position: sticky;
-  bottom: var(--v6d62e58c);
+  bottom: var(--v5631fb30);
   z-index: 9;
   margin-top: 0;
   padding-top: 10px;
   background: var(--dc-core-surface, var(--el-bg-color));
   box-shadow: 0 -1px 0 0 var(--dc-core-border-color, var(--el-border-color-lighter));
 }
-.list-layout[data-v-5301293b] .el-loading-mask {
+.list-layout[data-v-8527d1df] .el-loading-mask {
   left: -10px;
   top: -10px;
   right: -10px;
@@ -773,15 +1152,15 @@ to {
   gap: 8px;
   margin-top: 8px;
 }
-.view-layout[data-v-e6c42f0b] {
+.view-layout[data-v-773e43bd] {
   display: flex;
   flex-direction: column;
   gap: 8px;
 }
-.view-layout-toolbar[data-v-e6c42f0b] {
+.view-layout-toolbar[data-v-773e43bd] {
   display: flex;
   justify-content: flex-end;
 }
-.view-layout-content[data-v-e6c42f0b] {
+.view-layout-content[data-v-773e43bd] {
   overflow: auto;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "内部前端库",
   "private": false,
   "main": "es/index.mjs",
@@ -80,5 +80,5 @@
     "node": ">=18.0.0",
     "pnpm": ">=9.0.0"
   },
-  "gitHead": "d845acbde4360ef723ffca4fc3ee53d533798def"
+  "gitHead": "3244d757160572a4c0aacd7704edefa072ade111"
 }

package/src/components/app-layout/docs/README-AppLayout.md

@@ -46,6 +46,10 @@ App.vue 总装配——三个必填注入 + 两个必填内容锚即完整可跑
 | `userStore` | `AppLayoutUserStoreSlice<UserInfo>`（必填） | — | 用户 store 窄化实例（USER_STORE_KEY） |
 | `watermarkContent` | `WatermarkProps["content"]` | 无默认 | 水印内容；空数组/空串/undefined 则关闭水印 |
 | `sidebarAboveHeader` | `boolean` | `false` | sidebar z-index 高于 header |
+| `globalModalConfig` | `RegisterEntry[]`（非必需） | 无默认 | 全局弹窗配置数组（shelf 限定 `"app"`）——全局登录 / 配置等通用弹窗的注册入口，直接传给 AppLayout 内部专用 ModalPorter（Symbol 模式，只收 app 级） |
+| `enableGlobalImagePreview` | `boolean` | `false` | 是否开启全局图片预览弹窗：开启后内部给 `globalModalConfig` **拼接**内置配置项 `{ key: APP_GLOBAL_IMAGE_PREVIEW_KEY, component: ModalImagePreview, shelf: "app" }`——消费方零配置拿全局图片预览，**命令式** `globalModalRemote.evoke(APP_GLOBAL_IMAGE_PREVIEW_KEY, { src })` 开图（点击路径不走它——ImagePreviewTrigger/ElImage 原生直达） |
+| `enableGlobalVideoPreview` | `boolean` | `false` | 是否开启全局视频预览弹窗：开启后内部给 `globalModalConfig` **拼接**内置配置项 `{ key: APP_GLOBAL_VIDEO_PREVIEW_KEY, component: ModalVideoPreview, shelf: "app" }`——消费方零配置拿全局视频预览，触发端 `VideoPreviewTrigger` 经遥控器按此 key 唤起 |
+| `v-model:globalModalRemote` | `GlobalModalRemote` | `() => ({})` | 全局弹窗遥控器对象：应用根（App.vue）持有后按 key 遥控全局弹窗（evoke / close / update）；AppLayout 透传给内置 app 级 ModalShelf（`v-model:remote`）挂载句柄 |
 
 ### Emits
 
@@ -67,6 +71,50 @@ App.vue 总装配——三个必填注入 + 两个必填内容锚即完整可跑
 
 无
 
+### 全局弹窗遥控器（`globalModalRemote`，应用根范式）
+
+**性质**：AppLayout 把全局弹窗的控制面以 `v-model:globalModalRemote` 显式交给应用根（App.vue 持有遥控器）——**app 级弹窗只经这里注册 + 遥控**；全局唯一、与 app 同寿（AppLayout 常驻），不随路由切换销毁。**page 级弹窗不受影响**（页面内 Porter + page 架子，随页面生命周期）——两套入口各管各的层级。
+
+**类型**：`GlobalModalRemote = Record<string, GlobalModalControl> & { modalKey: string[] }`——按业务 key 寻址，句柄三件套（`evoke(payload?)` / `close()` / `update(payload)`）；**`modalKey` = 已注册全局弹窗 key 清单**（架子 `registerConfig` 同步维护），触发端等调用方用 `modalKey.includes(key)` 显式判断「该 key 是否已注册」（`evoke` 无返回值，未注册直接调会 TypeError）；重复 `evoke` 是重新打开还是更新由 `globalModalConfig` 条目配置期 `sameKeyStrategy`（`recreate` / `update`）决定。
+
+**应用根消费范式**（App.vue）：
+
+```vue
+<script lang="ts" setup>
+import { ref } from "vue";
+import { AppLayout } from "@done-coding/admin-core";
+
+/** 全局弹窗配置（shelf 限定 "app"）——注册入口 */
+const globalModalConfig = [
+  { key: "globalLogin", component: GlobalLoginModal, shelf: "app" },
+];
+/** 遥控器：App.vue 持有，可随时 evoke / close / update 全局弹窗 */
+const globalModalRemote = ref({});
+</script>
+
+<template>
+  <AppLayout
+    v-model:globalModalRemote="globalModalRemote"
+    :global-modal-config="globalModalConfig"
+    :bridge="appCoreBridge"
+    :appStore="appStore"
+    :userStore="userStore"
+  >
+    <!-- 业务锚槽 -->
+  </AppLayout>
+</template>
+
+<script lang="ts" setup>
+// 任意位置遥控（经 inject 或直传）：
+// globalModalRemote.value.globalLogin?.evoke({ user: "x" });   // 打开
+// globalModalRemote.value.globalLogin?.close();                // 关闭（全局弹窗不能只靠用户点击关闭）
+</script>
+```
+
+**机制链路**：`globalModalConfig`（入）→ AppLayout 内部专用 ModalPorter（`globalOnly` Symbol 模式，只收 app 级）推送 → 内置 app 级 ModalShelf 挂载句柄进 remote（`v-model:remote`，`modalKey` 同步维护）→ 应用根遥控。无 provide——遥控器对象经 v-model 链直传（core 另导出注入 key `GLOBAL_MODAL_REMOTE_KEY` 供触发组件等消费端 inject，App 根 provide 同一对象即可接通）。
+
+**全局预览弹窗拼接**：`enableGlobalImagePreview` / `enableGlobalVideoPreview` 开启时，AppLayout 把内置两项**拼进**传给专用 Porter 的配置数组（`[...globalModalConfig, 内置项]`，shelf:"app"）——业务 key 与预置 key 平级共处 remote（`modalKey` 均收录）。**命令式入口**（不经过点击）：`globalModalRemote.evoke(APP_GLOBAL_*_PREVIEW_KEY, payload)` 即开图/开视频（视频触发端 `VideoPreviewTrigger` 的点击决策链也经 `modalKey.includes` 命中后走此入口；图片触发端点击直达 ElImage 原生预览，不经全局）。关掉开关即整项摘除（`unregisterConfig` 同步清理）。
+
 ## 反模式 / 注意
 
 - **别找 AppLayout 的默认 slot**：页面内容由 AppBody（内置 RouterView）渲染，AppLayout 只承接内容锚

package/src/components/app-layout/docs/README-AppPage.md

@@ -30,7 +30,7 @@
 
 ## 能力边界 / 按需使用
 
-- **四向悬浮插槽（`#top`/`#bottom`/`#left`/`#right`）：默认全关、常规页面不需要。** 仅当页面需要「悬浮于内容之上的固定补充区」（通栏操作条 / 侧边抽屉 / 浮动提示）才开对应槽——判据：内容必须 fixed 悬浮且不参与文档流（top/bottom 通栏量高 → padding 让位，left/right 量宽）。列表/表单/详情常规页一律不开。
+- **四向悬浮插槽（`#top`/`#bottom`/`#left`/`#right`）：默认全关、常规页面不需要。** 仅当页面需要「悬浮于内容之上的固定补充区」（通栏操作条 / 侧边抽屉 / 浮动提示）才开对应槽——判据：内容必须 fixed 悬浮且不参与文档流（top/bottom 通栏量高 → padding 让位，left/right 量宽）。列表/表单/详情常规页一律不开。**`#left`/`#right` 内放列表时用 scope 的 `listLayoutRecommended`（见 API）拿窄栏推荐配置，[MUST NOT] 自行拍脑袋配窄栏列表形态。**
 - `topBg`/`bottomBg`/`leftBg`/`rightBg`：仅悬浮槽需要着色时设，默认无背景即够用。
 - `*ObserveResize`：仅当槽内内容有 CSS 过渡折叠 / 异步撑开（不触发重渲染的尺寸变化）才开对应 RO；普通槽内容（v-if/v-show/静态）不开。
 - `fullMode`：默认 `"min-height"` 即够用；`"height"` 仅当页面内子级依赖硬高撑满（如顶级自撑 TabsMain）时选。
@@ -61,7 +61,42 @@
 | --- | --- | --- |
 | `default` | 无 | 页面主体（ModalShelf page 层包裹） |
 | `#top` / `#bottom` | 无 | 通栏悬浮槽（量高 → padding-top/bottom） |
-| `#left` / `#right` | 无 | 侧向悬浮槽（量宽） |
+| `#left` / `#right` | `{ listLayoutRecommended }` | 侧向悬浮槽（量宽）——scope 携带窄栏 ListLayout 推荐配置（见下） |
+
+### `#left` / `#right` scope：`listLayoutRecommended`（窄栏 ListLayout 推荐配置）
+
+**性质**：固定内置推荐值（写死、非运行时开关、不做响应式探测），仅经 `#left`/`#right` 插槽 scoped 带出。面向「列表放进 left/right 窄栏」的展示形态推荐；消费者拿到后直接 `v-bind` 展开进 ListLayout，可按需 spread 覆盖（`v-bind="{ ...listLayoutRecommended, customView: false }"`）。
+
+**形状**（与 ListLayout props 平铺对齐）：
+
+| 字段 | 类型 | 固定值 | 语义 |
+| --- | --- | --- | --- |
+| `customView` | `boolean` | `true` | 开启自定义视图（DataListView 卡片形态替代 ElTable——窄栏过窄表格必然崩，卡片更优）。需配套 ListLayout `#custom-view-item` 定义单项 |
+| `tableMainProps.pageLayout` | `string` | `"prev, pager, next"` | 分页器最简形态——去 total/sizes/jumper，仅页码（`« 1 2 3 4 5 »`） |
+| `tableMainProps.paginationBackground` | `boolean` | `false` | 页码不带背景框（透传 ElPagination `background=false` 纯数字链接形态；TableMain 默认 `true` 带框） |
+
+**消费示例**（`#left`/`#right` 内放列表）：
+
+```vue
+<AppPage>
+  <template #left="{ listLayoutRecommended }">
+    <ListLayout
+      v-bind="listLayoutRecommended"
+      :api="leftApi"
+      :columns="leftColumns"
+    >
+      <template #custom-view-item="{ item }">
+        <!-- 窄栏卡片单项 -->
+      </template>
+    </ListLayout>
+  </template>
+  <template #default>
+    <!-- 主内容区 -->
+  </template>
+</AppPage>
+```
+
+**类型**：`AppPageListLayoutRecommended`（`app-layout/types.ts` 导出，非泛型——与 ListLayout 泛型 props 无关的平铺子集）。
 
 ### Expose
 
@@ -72,9 +107,12 @@
 - **悬浮槽尺寸变化来自 CSS 过渡/异步撑开 → 必须开对应 `observeResize`**（onUpdated 只读渲染后瞬时值，过渡动画读起点漏最终）
 - 四向槽 fixed 定位——内容滚动时悬浮不动，属设计语义，勿误当普通 inline 槽
 - 槽尺寸/inset 几何由 `app-page-geometry` 纯函数计算导出，[MUST NOT] 手写自造
+- `listLayoutRecommended` 开 `customView` 后 [MUST] 配套 ListLayout `#custom-view-item`，否则窄栏卡片渲染为空
+- `listLayoutRecommended` 是 AppPage → ListLayout 的**定向耦合**（AppPage 持有 ListLayout prop 形状子集），属本能力设计使然；若 ListLayout 该子集发生 breaking，[MUST] 同步更新 `app-layout/types.ts` 与本 README
 
 ## 关联
 
 - 几何纯函数：`app-page-geometry.ts`（computeAppPageReducedViewportHeight/Width、computeAppPageContentInset、computeAppPageSlotStyles、computeAppPageSlotShimStyles + `APP_PAGE_SLOT_Z_INDEX`=1）
 - 高度链：AppBody provide 的 `BODY_CONTENT_VIEWPORT_HEIGHT` / `BODY_CONTENT_VIEWPORT_RECT` / `BODY_CONTENT_VIEWPORT_INSET` / `SCOPE_VIEWPORT_MAX_HEIGHT`
 - 范式页：`apps/reference/src/pages/app-layout/page-slots/`（含 ChainReadout 高度链互动面板）
+- 窄栏列表范式：`apps/reference/src/pages/app-layout/narrow-list/`（#left/#right 放 ListLayout + `listLayoutRecommended`，与裸用对照）