@agile-team/wl-skills-ui 1.9.14 → 1.9.15

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to **@agile-team/wl-skills-ui** will be documented in this f
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.9.15] - 2026-08-10
+
+### Added
+
+- 新增 `normalizeColumnAlignment(s)` 运行时能力，把业务显式声明的 `align/headerAlign` 桥接为 BaseTable/AG Grid 可消费的 `cellStyle/headerClass`，并递归覆盖分组列。
+- 新增行为与样式契约测试，覆盖无声明不接管、左右/居中对齐、分组列以及业务自定义样式优先级。
+
+### Fixed
+
+- 修复部分平台 AG Grid 适配器忽略列定义 `align/headerAlign`，导致业务明确要求居中或右对齐却仍按默认布局展示的问题。
+
+### Changed
+
+- `defineColumns()` 自动应用显式对齐桥接；未声明对齐的普通列保持原状，已有 `cellStyle/headerClass` 不覆盖，不引入全局居中规则。
+
 ## [1.9.14] - 2026-08-10
 
 ### Added

package/README.md

@@ -213,7 +213,7 @@ yarn add @agile-team/wl-skills-ui
 |---|---|---|
 | `element-plus` | **`2.2.6-prod.3`** | 集团 jh- 定制版；EP 2.3.0 起引入 `.el-input__wrapper`，与 jh-ui 3.x 不兼容 |
 | `@jhlc/jh-ui` | **`3.1.0`** | SCSS 皮肤包，`.com-text` label 包裹 + `.has-colon` 冒号注入（wl-skills-ui 已统一屏蔽表单冒号） |
-| `@agile-team/wl-skills-ui` | `^1.9.14` | 已对齐上述组合的 DOM 假设、客户主题锁、圆角契约、复合数字框、跨浏览器字体、AG Grid 原生对齐与定制页边界 |
+| `@agile-team/wl-skills-ui` | `^1.9.15` | 已对齐上述组合的 DOM 假设、客户主题锁、圆角契约、复合数字框、跨浏览器字体、显式列对齐与定制页边界 |
 
 三种识别方式，任选其一：
 
@@ -227,7 +227,15 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.9.14：
+当前 v1.9.15：
+
+- **显式列对齐跨表格生效**：`defineColumns()` 会把业务明确声明的 `align/headerAlign`
+  桥接为 BaseTable/AG Grid 能稳定消费的 `cellStyle/headerClass`，Element Table 继续读取原属性；
+  无声明时不设置默认对齐，已有业务样式不覆盖，分组列递归处理。
+- **零布局污染边界**：包只修复“显式意图未被平台适配器消费”，不把普通列全局居中，
+  不接管选择列、语义渲染或业务自定义 `cellStyle/headerClass`。
+
+上一版 v1.9.14：
 
 - **Edge/Chrome 字体收敛**：受管 Element、BaseTable 与 AG Grid 统一使用覆盖中英文数字的
   `--wk-font-family-sans`，AG 表头/正文使用整数 13px；不改写 `body/*`，登录页、大屏、
@@ -714,7 +722,8 @@ export const myRules = [
 
 | API                                              | 说明                                               |
 | ------------------------------------------------ | -------------------------------------------------- |
-| `defineColumns(cols)`                            | 列定义，自动应用 `COLUMN_AUTO_MAP`                 |
+| `defineColumns(cols)`                            | 列定义，应用自动映射并桥接显式列对齐               |
+| `normalizeColumnAlignments(cols)`                | 仅桥接显式 `align/headerAlign`，不设置默认对齐      |
 | `renderOps(items)`                               | 操作列图标按钮组（view/edit/del/log/ok/send 预设） |
 | `renderTagNode(v, map)`                          | 状态 Tag 渲染                                      |
 | `renderClassifyTag(v, map)`                      | 分类 Tag 渲染                                      |

package/docs/compat-matrix.md

@@ -11,7 +11,7 @@
 | `element-plus` | **`2.2.6-prod.3`** | 集团 jh- 定制版，搭配 `@jhlc/jh-ui` 使用，DOM 仍为 `.el-input > .el-input__inner` 直挂结构（**EP 2.3.0 起才引入 `.el-input__wrapper`**） |
 | `@jhlc/jh-ui` | **`3.1.0`** | SCSS 皮肤包，`.com-text` label 包裹、`.has-colon ::after` 冒号注入、`.el-form-item--default { margin-bottom: 24px }` 等强约束 |
 | `@jhlc/common-core` | `3.1.0` 或 `3.1.0-prod.x` | 基础 util/types，`@jhlc/jh-ui` 间接依赖 |
-| `@agile-team/wl-skills-ui` | `^1.9.14` | 已对齐 jh-ui 3.1.0 + EP 2.2.6-prod.3 的 DOM 假设、客户主题锁、6px 基础圆角、紧凑表单、复合数字框、跨浏览器字体、AG Grid 原生对齐与定制页边界 |
+| `@agile-team/wl-skills-ui` | `^1.9.15` | 已对齐 jh-ui 3.1.0 + EP 2.2.6-prod.3 的 DOM 假设、客户主题锁、6px 基础圆角、紧凑表单、复合数字框、跨浏览器字体、显式列对齐与定制页边界 |
 
 ## 项目集群当前实测
 
@@ -35,7 +35,7 @@
 
 ## 适配建议
 
-- 集团内项目：**统一锚定 `element-plus@2.2.6-prod.3` + `@jhlc/jh-ui@3.1.0`**，与 wl-skills-ui v1.9.14 三方对齐。
+- 集团内项目：**统一锚定 `element-plus@2.2.6-prod.3` + `@jhlc/jh-ui@3.1.0`**，与 wl-skills-ui v1.9.15 三方对齐。
 - Skin 项目除全局样式外，在 `main.ts` 引入一次 `@agile-team/wl-skills-ui/runtime/auto`；Native 项目的 `installCommonPreset()` 已包含相同包级保护，不要重复安装。
 - 升级 `element-plus` 到 2.3+ 前，必须同步升级 `@jhlc/jh-ui` 到对应支持版本，否则 `.com-text` / `.el-input__inner` DOM 与 EP `__wrapper` 体系不兼容。
 - 新项目接入：见 README 「快速接入」章节，默认会按本表声明 peerDependency 范围。

package/es/{chunk-4IOYRBW4.js → chunk-53TF2NQQ.js}

@@ -2,7 +2,33 @@ import { h } from 'vue';
 import { ElTag } from 'element-plus';
 import { Upload, CircleCheck, Document, Delete, Edit, View } from '@element-plus/icons-vue';
 
-// runtime/core/renderers.ts
+// runtime/core/alignment.ts
+var HEADER_ALIGNMENT_CLASS = {
+  left: "wl-ui-table-header-align--left",
+  center: "wl-ui-table-header-align--center",
+  right: "wl-ui-table-header-align--right"
+};
+function isColumnAlignment(value) {
+  return value === "left" || value === "center" || value === "right";
+}
+function normalizeColumnAlignment(column) {
+  const normalizedChildren = Array.isArray(column.children) ? normalizeColumnAlignments(column.children) : column.children;
+  const align = isColumnAlignment(column.align) ? column.align : void 0;
+  const headerAlign = isColumnAlignment(column.headerAlign) ? column.headerAlign : align;
+  const needsChildren = normalizedChildren !== column.children;
+  const needsCellStyle = Boolean(align) && column.cellStyle === void 0;
+  const needsHeaderClass = Boolean(headerAlign) && column.headerClass === void 0;
+  if (!needsChildren && !needsCellStyle && !needsHeaderClass) return column;
+  return {
+    ...column,
+    ...needsChildren ? { children: normalizedChildren } : {},
+    ...needsCellStyle ? { cellStyle: { textAlign: align } } : {},
+    ...needsHeaderClass ? { headerClass: HEADER_ALIGNMENT_CLASS[headerAlign] } : {}
+  };
+}
+function normalizeColumnAlignments(columns) {
+  return columns.map((column) => normalizeColumnAlignment(column));
+}
 var ENABLE_STATUS_MAP = {
   0: { label: "\u505C\u7528", type: "danger" },
   1: { label: "\u542F\u7528", type: "success" }
@@ -286,18 +312,20 @@ function defineColumns(columns) {
     const fieldName = normalized.name ?? normalized.label ?? "";
     const preset = COLUMN_AUTO_MAP[fieldName];
     const hasRenderer = normalized.defaultNode !== void 0 || normalized.defaultSlot !== void 0;
-    if (hasRenderer) return normalized;
+    if (hasRenderer) return normalizeColumnAlignment(normalized);
     if (!preset && isDictColumn(normalized)) {
-      return {
+      return normalizeColumnAlignment({
         ...normalized,
         defaultSlot: ({ row }) => renderDictClassifyTag(
           row?.[fieldName],
           String(normalized.logicValue)
         )
-      };
+      });
     }
-    if (!preset) return withOverflowTooltip(normalized);
-    return withOverflowTooltip({ ...preset, ...normalized });
+    if (!preset) return normalizeColumnAlignment(withOverflowTooltip(normalized));
+    return normalizeColumnAlignment(
+      withOverflowTooltip({ ...preset, ...normalized })
+    );
   });
 }
 function isDictColumn(col) {
@@ -328,4 +356,4 @@ registerColumnAutoMaps({
   }
 });
 
-export { AUDIT_STATUS_MAP, ENABLE_STATUS_MAP, RATING_LEVEL_COLORS, VERIFY_STATUS_MAP, clearColumnAutoMap, defineColumns, getColumnAutoMap, registerColumnAutoMap, registerColumnAutoMaps, registerDictColorMap, registerDictColorMaps, renderAuditStatus, renderBadge, renderClassifyTag, renderCountBadge, renderDangerText, renderDictClassifyTag, renderEnableStatus, renderOps, renderRatingLevel, renderTagNode, renderTagSlot, renderVerifyStatus, setDictResolver };
+export { AUDIT_STATUS_MAP, ENABLE_STATUS_MAP, RATING_LEVEL_COLORS, VERIFY_STATUS_MAP, clearColumnAutoMap, defineColumns, getColumnAutoMap, normalizeColumnAlignment, normalizeColumnAlignments, registerColumnAutoMap, registerColumnAutoMaps, registerDictColorMap, registerDictColorMaps, renderAuditStatus, renderBadge, renderClassifyTag, renderCountBadge, renderDangerText, renderDictClassifyTag, renderEnableStatus, renderOps, renderRatingLevel, renderTagNode, renderTagSlot, renderVerifyStatus, setDictResolver };

package/es/common-preset.d.ts

@@ -1,7 +1,7 @@
 import * as vue from 'vue';
 import { VNode } from 'vue';
-import { T as TagMapItem, J as JhTagNode } from './types-Dnh4U0hw.js';
-export { r as registerDictColorMap, a as registerDictColorMaps, b as renderDictClassifyTag, s as setDictResolver } from './renderers-B3uUAze8.js';
+import { T as TagMapItem, J as JhTagNode } from './types-DtmxwMWV.js';
+export { r as registerDictColorMap, a as registerDictColorMaps, b as renderDictClassifyTag, s as setDictResolver } from './renderers-DlFRBX9K.js';
 
 declare const RISK_LEVEL_MAP: Record<string | number, TagMapItem>;
 declare const renderRiskLevel: (v: string | number | null | undefined) => JhTagNode | null;

package/es/common-preset.js

@@ -1,6 +1,6 @@
 import { installUiRuntimeGuards } from './chunk-QLPJLXY6.js';
-import { renderTagNode, renderClassifyTag, registerColumnAutoMaps, renderRatingLevel, renderBadge } from './chunk-4IOYRBW4.js';
-export { registerDictColorMap, registerDictColorMaps, renderDictClassifyTag, setDictResolver } from './chunk-4IOYRBW4.js';
+import { renderTagNode, renderClassifyTag, registerColumnAutoMaps, renderRatingLevel, renderBadge } from './chunk-53TF2NQQ.js';
+export { registerDictColorMap, registerDictColorMaps, renderDictClassifyTag, setDictResolver } from './chunk-53TF2NQQ.js';
 import './chunk-Q3N5QNRZ.js';
 
 // runtime/presets/common.ts

package/es/index.d.ts

@@ -1,8 +1,21 @@
-import { C as ColumnLike } from './types-Dnh4U0hw.js';
-export { E as ElTagType, J as JhTagNode, a as OpChip, O as OpItem, b as OpLink, c as OpPreset, T as TagMapItem } from './types-Dnh4U0hw.js';
-export { A as AUDIT_STATUS_MAP, E as ENABLE_STATUS_MAP, R as RATING_LEVEL_COLORS, V as VERIFY_STATUS_MAP, r as registerDictColorMap, a as registerDictColorMaps, c as renderAuditStatus, d as renderBadge, e as renderClassifyTag, f as renderCountBadge, g as renderDangerText, b as renderDictClassifyTag, h as renderEnableStatus, i as renderOps, j as renderRatingLevel, k as renderTagNode, l as renderTagSlot, m as renderVerifyStatus, s as setDictResolver } from './renderers-B3uUAze8.js';
+import { C as ColumnLike } from './types-DtmxwMWV.js';
+export { E as ElTagType, J as JhTagNode, a as OpChip, O as OpItem, b as OpLink, c as OpPreset, T as TagMapItem } from './types-DtmxwMWV.js';
+export { A as AUDIT_STATUS_MAP, E as ENABLE_STATUS_MAP, R as RATING_LEVEL_COLORS, V as VERIFY_STATUS_MAP, r as registerDictColorMap, a as registerDictColorMaps, c as renderAuditStatus, d as renderBadge, e as renderClassifyTag, f as renderCountBadge, g as renderDangerText, b as renderDictClassifyTag, h as renderEnableStatus, i as renderOps, j as renderRatingLevel, k as renderTagNode, l as renderTagSlot, m as renderVerifyStatus, s as setDictResolver } from './renderers-DlFRBX9K.js';
 import 'vue';
 
+type ColumnAlignment = "left" | "center" | "right";
+/**
+ * 将业务显式声明的 align/headerAlign 转换为 BaseTable/AG Grid 能稳定消费的配置。
+ *
+ * - 没有显式对齐声明时原样返回，不改变项目默认布局；
+ * - 已有 cellStyle/headerClass 时尊重业务配置，不覆盖；
+ * - 递归处理分组列 children；
+ * - Element Table 仍直接消费原有 align/headerAlign。
+ */
+declare function normalizeColumnAlignment<T extends ColumnLike>(column: T): T;
+/** 批量规范化列定义；只桥接显式对齐意图，不设置全局默认对齐。 */
+declare function normalizeColumnAlignments<T extends ColumnLike>(columns: T[]): T[];
+
 /**
  * runtime/core/registry.ts — COLUMN_AUTO_MAP 注册中心 + defineColumns
  *
@@ -196,4 +209,4 @@ declare function uninstallSplitGridResizeGuard(): void;
  */
 declare function installUiRuntimeGuards(): void;
 
-export { BRAND_THEME_TOKENS, ColumnLike, type OverflowTooltipGuardOptions, type PresetConfig, SPLIT_GRID_RESIZE_EVENT, type SplitGridResizeDetail, clearColumnAutoMap, createPreset, defineColumns, getColumnAutoMap, getInstalledPresets, installBrandThemeLock, installOverflowTooltipGuard, installPreset, installSplitGridResizeGuard, installUiRuntimeGuards, registerColumnAutoMap, registerColumnAutoMaps, uninstallOverflowTooltipGuard, uninstallSplitGridResizeGuard };
+export { BRAND_THEME_TOKENS, type ColumnAlignment, ColumnLike, type OverflowTooltipGuardOptions, type PresetConfig, SPLIT_GRID_RESIZE_EVENT, type SplitGridResizeDetail, clearColumnAutoMap, createPreset, defineColumns, getColumnAutoMap, getInstalledPresets, installBrandThemeLock, installOverflowTooltipGuard, installPreset, installSplitGridResizeGuard, installUiRuntimeGuards, normalizeColumnAlignment, normalizeColumnAlignments, registerColumnAutoMap, registerColumnAutoMaps, uninstallOverflowTooltipGuard, uninstallSplitGridResizeGuard };

package/es/index.js

@@ -1,6 +1,6 @@
 export { SPLIT_GRID_RESIZE_EVENT, installOverflowTooltipGuard, installSplitGridResizeGuard, installUiRuntimeGuards, uninstallOverflowTooltipGuard, uninstallSplitGridResizeGuard } from './chunk-QLPJLXY6.js';
-import { registerColumnAutoMaps } from './chunk-4IOYRBW4.js';
-export { AUDIT_STATUS_MAP, ENABLE_STATUS_MAP, RATING_LEVEL_COLORS, VERIFY_STATUS_MAP, clearColumnAutoMap, defineColumns, getColumnAutoMap, registerColumnAutoMap, registerColumnAutoMaps, registerDictColorMap, registerDictColorMaps, renderAuditStatus, renderBadge, renderClassifyTag, renderCountBadge, renderDangerText, renderDictClassifyTag, renderEnableStatus, renderOps, renderRatingLevel, renderTagNode, renderTagSlot, renderVerifyStatus, setDictResolver } from './chunk-4IOYRBW4.js';
+import { registerColumnAutoMaps } from './chunk-53TF2NQQ.js';
+export { AUDIT_STATUS_MAP, ENABLE_STATUS_MAP, RATING_LEVEL_COLORS, VERIFY_STATUS_MAP, clearColumnAutoMap, defineColumns, getColumnAutoMap, normalizeColumnAlignment, normalizeColumnAlignments, registerColumnAutoMap, registerColumnAutoMaps, registerDictColorMap, registerDictColorMaps, renderAuditStatus, renderBadge, renderClassifyTag, renderCountBadge, renderDangerText, renderDictClassifyTag, renderEnableStatus, renderOps, renderRatingLevel, renderTagNode, renderTagSlot, renderVerifyStatus, setDictResolver } from './chunk-53TF2NQQ.js';
 export { BRAND_THEME_TOKENS, installBrandThemeLock } from './chunk-Q3N5QNRZ.js';
 
 // runtime/presets/registry.ts

package/es/presets/security.d.ts

@@ -1,4 +1,4 @@
-import { T as TagMapItem, J as JhTagNode } from '../types-Dnh4U0hw.js';
+import { T as TagMapItem, J as JhTagNode } from '../types-DtmxwMWV.js';
 import 'vue';
 
 declare const VIOLATION_STATUS_MAP: Record<string | number, TagMapItem>;

package/es/presets/security.js

@@ -1,4 +1,4 @@
-import { renderTagNode, registerDictColorMaps, registerColumnAutoMaps } from '../chunk-4IOYRBW4.js';
+import { renderTagNode, registerDictColorMaps, registerColumnAutoMaps } from '../chunk-53TF2NQQ.js';
 import { installBrandThemeLock } from '../chunk-Q3N5QNRZ.js';
 
 // runtime/presets/security.ts

package/es/{renderers-B3uUAze8.d.ts → renderers-DlFRBX9K.d.ts}

@@ -1,5 +1,5 @@
 import { VNode } from 'vue';
-import { T as TagMapItem, J as JhTagNode, O as OpItem } from './types-Dnh4U0hw.js';
+import { T as TagMapItem, J as JhTagNode, O as OpItem } from './types-DtmxwMWV.js';
 
 /**
  * runtime/core/renderers.ts — 通用渲染器 + 通用状态映射

package/es/{types-Dnh4U0hw.d.ts → types-DtmxwMWV.d.ts}

@@ -27,6 +27,11 @@ interface ColumnLike {
     width?: number | string;
     fixed?: string | boolean;
     type?: string;
+    align?: "left" | "center" | "right";
+    headerAlign?: "left" | "center" | "right";
+    cellStyle?: Record<string, unknown> | ((params: any) => Record<string, unknown>);
+    headerClass?: string | string[] | ((params: any) => string | string[]);
+    children?: ColumnLike[];
     defaultNode?: (ctx: {
         row: any;
     }) => any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.9.14",
+  "version": "1.9.15",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",

package/styles/vendors/_ag-grid.scss

@@ -94,6 +94,20 @@
   width: 100%;
 }
 
+// 仅响应列定义显式声明的 headerAlign/align；不设置全局默认对齐。
+// runtime/defineColumns 会把该意图桥接为下列类，兼容平台 BaseTable 的 AG Grid 适配层。
+.ag-header-cell.wl-ui-table-header-align--left .ag-header-cell-label {
+  justify-content: flex-start;
+}
+
+.ag-header-cell.wl-ui-table-header-align--center .ag-header-cell-label {
+  justify-content: center;
+}
+
+.ag-header-cell.wl-ui-table-header-align--right .ag-header-cell-label {
+  justify-content: flex-end;
+}
+
 .ag-header-cell-text {
   font-size: 13px;
   font-weight: 600;