km-card-layout-core 0.1.10 → 0.1.12

package/index.ts

@@ -1,513 +1,21 @@
-/**
- * CardMaster 布局 JSON 渲染核心。
- *
- * - 平台无关：不依赖 DOM/小程序 API，方便在 Web/小程序/Node 复用。
- * - 职责：将布局 Schema 与业务数据合成为带内联样式的渲染树，外层只需将节点映射到各端组件。
- */
-
-import type {
-  AbsoluteLayoutDefinition,
-  CardElement,
-  CardElementType,
-  IconElement,
-  ImageElement,
-  LayoutPanelElement,
-  TextElement,
-} from './interface/elements';
-import type { CardLayoutInput, CardLayoutSchema } from './interface/layout';
-import type {
-  BindingContext,
-  RenderNode,
-  RenderPageResult,
-  RenderResult,
-} from './interface/render';
-
-export * from './interface/index';
-
-/** ---------- 常量 ---------- */
-
-const DEFAULT_CARD_WIDTH = 343; // 默认卡片宽度（像素）
-const DEFAULT_CARD_HEIGHT = 210; // 默认卡片高度（像素）
-
-const DIMENSION_PROPS = new Set<string>([
-  'width',
-  'height',
-  'top',
-  'right',
-  'bottom',
-  'left',
-  'padding',
-  'paddingTop',
-  'paddingBottom',
-  'paddingLeft',
-  'paddingRight',
-  'margin',
-  'marginTop',
-  'marginBottom',
-  'marginLeft',
-  'marginRight',
-  'fontSize',
-  'lineHeight',
-  'borderRadius',
-  'borderWidth',
-  'letterSpacing',
-  'gap',
-  'rowGap',
-  'columnGap',
-]);
-
-/** ---------- 基础工具 ---------- */
-/**
- * 安全转 number，非数值或 NaN 返回 undefined。
- */
-const toNumber = (value: unknown): number | undefined => {
-  const num = Number(value);
-  return Number.isFinite(num) ? num : undefined;
-};
-/**
- * camelCase 转 kebab-case（用于内联样式 key）。
- */
-const toKebab = (key: string): string =>
-  key.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
-/**
- * 数字追加单位，非数字原样转字符串。
- * 数字追加单位，非数字原样转字符串。
- */
-export const addUnit = (
-  value: string | number | undefined | null,
-  unit: 'px' | 'rpx'
-): string | undefined => {
-  if (value === undefined || value === null || value === '') return undefined;
-  if (typeof value === 'number') {
-    const ratio = unit === 'rpx' ? 2 : 1;
-    return `${value * ratio}${unit}`;
-  }
-  if (typeof value === 'string') {
-    const parsed = Number(value);
-    if (Number.isFinite(parsed)) {
-      const ratio = unit === 'rpx' ? 2 : 1;
-      return `${parsed * ratio}${unit}`;
-    }
-  }
-  return `${value}`;
-};
-/**
- * 样式对象转内联样式字符串，对需要单位的字段自动补单位。
- */
-export const styleObjectToString = (
-  style?: Record<string, any>,
-  unit: 'px' | 'rpx' = 'px'
-): string => {
-  if (!style) return '';
-  const pairs: string[] = [];
-  Object.keys(style).forEach(key => {
-    const value = style[key];
-    if (value === undefined || value === null || value === '') return;
-    const useUnit = DIMENSION_PROPS.has(key)
-      ? addUnit(value as any, unit)
-      : value;
-    if (useUnit === undefined || useUnit === null || useUnit === '') return;
-    pairs.push(`${toKebab(key)}:${useUnit}`);
-  });
-  return pairs.join(';');
-};
-
-/**
- * 容错 JSON 解析：字符串用 JSON.parse，其他保持原样或返回 null。
- */
-const parseJson = (input: unknown): any | null => {
-  if (typeof input !== 'string') return input ?? null;
-  try {
-    return JSON.parse(input);
-  } catch (err) {
-    console.warn('[km-card-layout-core] JSON parse failed', err);
-    return null;
-  }
-};
-
-const isObject = (val: unknown): val is Record<string, any> | any[] =>
-  Boolean(val) && typeof val === 'object';
-
-const getAbsLayout = (el: CardElement): AbsoluteLayoutDefinition | null =>
-  el.layout && el.layout.mode === 'absolute'
-    ? (el.layout as AbsoluteLayoutDefinition)
-    : null;
-
-/** ---------- 布局与数据解析 ---------- */
-
-/**
- * 归一化布局输入（对象或 JSON 字符串），补齐宽高/容器/children 默认值。
- */
-export const normalizeLayout = (
-  layout: CardLayoutInput
-): CardLayoutSchema[] => {
-  if (!Array.isArray(layout)) return [];
-  return layout
-    .map(item => {
-      if (!item || typeof item !== 'object') return null;
-      const parsed = item as CardLayoutSchema;
-      return {
-        ...parsed,
-        width: toNumber((parsed as any).width) ?? DEFAULT_CARD_WIDTH,
-        height: toNumber((parsed as any).height) ?? DEFAULT_CARD_HEIGHT,
-        container: (parsed as any).container || { mode: 'absolute' },
-        children: Array.isArray((parsed as any).children)
-          ? ((parsed as any).children as CardElement[])
-          : [],
-      };
-    })
-    .filter((v): v is CardLayoutSchema => Boolean(v));
-};
-
-/**
- * 将绑定路径拆分为片段，支持点语法与数组下标。
- */
-const pathToSegments = (path: string): string[] =>
-  `${path || ''}`
-    .replace(/\[(\d+)\]/g, '.$1')
-    .split('.')
-    .map(p => p.trim())
-    .filter(Boolean);
-
-/**
- * 按路径访问对象/数组，缺失时返回 undefined/null。
- */
-const readByPath = (data: any, path: string): any => {
-  if (path === undefined || path === null || path === '') return data;
-  const segments = pathToSegments(path);
-  let cursor: any = data;
-  for (let i = 0; i < segments.length; i += 1) {
-    if (!isObject(cursor) && !Array.isArray(cursor)) return undefined;
-    const key = segments[i];
-    if (Array.isArray(cursor)) {
-      const idx = Number(key);
-      cursor = Number.isNaN(idx) ? undefined : cursor[idx];
-    } else {
-      cursor = (cursor as Record<string, any>)[key];
-    }
-    if (cursor === undefined || cursor === null) {
-      return cursor;
-    }
-  }
-  return cursor;
-};
-/**
- * Resolve element binding against provided data.
- */
-export const resolveBindingValue = (
-  binding: string | undefined,
-  rootData: Record<string, any>,
-  context?: BindingContext
-): any => {
-  if (!binding) return undefined;
-  const value = readByPath(rootData, binding);
-  return value === undefined ? undefined : value;
-};
-
-/** ---------- 样式构建 ---------- */
-
-const buildCardStyle = (
-  layout: CardLayoutSchema,
-  unit: 'px' | 'rpx'
-): string =>
-  styleObjectToString(
-    {
-      width: addUnit(layout.width, unit),
-      height: addUnit(layout.height, unit),
-      color: layout.fontColor,
-      borderRadius:
-        layout.borderRadius !== undefined
-          ? addUnit(layout.borderRadius, unit)
-          : undefined,
-      padding:
-        layout.padding !== undefined ? addUnit(layout.padding, unit) : undefined,
-      position: 'relative',
-      overflow: 'hidden',
-      boxSizing: 'border-box',
-      backgroundColor: 'transparent',
-    },
-    unit
-  );
-
-const buildBackgroundStyle = (
-  layout: CardLayoutSchema,
-  unit: 'px' | 'rpx'
-): string =>
-  styleObjectToString(
-    {
-      zIndex: layout.backgroundZIndex,
-      borderRadius:
-        layout.borderRadius !== undefined
-          ? addUnit(layout.borderRadius, unit)
-          : undefined,
-      width: '100%',
-      height: '100%',
-      position: 'absolute',
-      left: 0,
-      top: 0,
-    },
-    unit
-  );
-
-/**
- * 生成元素外层样式（绝对/弹性布局），始终返回内联样式字符串。
- */
-const buildWrapperStyle = (el: CardElement, unit: 'px' | 'rpx'): string => {
-  const abs = getAbsLayout(el);
-  if (!abs) return '';
-
-  return styleObjectToString(
-    {
-      position: 'absolute',
-      left: addUnit(abs.x, unit),
-      top: addUnit(abs.y, unit),
-      width: addUnit(abs.width, unit),
-      height: addUnit(abs.height, unit),
-      zIndex: abs.zIndex,
-      boxSizing: 'border-box',
-    },
-    unit
-  );
-};
-const buildPanelContentStyle = (
-  el: LayoutPanelElement,
-  unit: 'px' | 'rpx'
-): string =>
-  styleObjectToString(
-    {
-      position: 'relative',
-      width: '100%',
-      height: '100%',
-      display: 'block',
-      boxSizing: 'border-box',
-      ...(el.style || {}),
-    },
-    unit
-  );
-
-const buildTextContentStyle = (el: TextElement, unit: 'px' | 'rpx') => {
-  const textAlign =
-    (el.style?.textAlign as string | undefined) || el.align || undefined;
-  const style: Record<string, any> = {
-    ...(el.style || {}),
-    whiteSpace: 'pre-wrap',
-    wordBreak: 'break-word',
-    lineHeight:
-      el.style?.lineHeight !== undefined && el.style?.lineHeight !== null
-        ? el.style.lineHeight
-        : '1.2',
-    display: 'inline-flex',
-    alignItems: 'center',
-  };
-  if (textAlign) style.textAlign = textAlign;
-  return styleObjectToString(style, unit);
-};
-
-const buildBaseContentStyle = (
-  el: CardElement,
-  unit: 'px' | 'rpx'
-): string =>
-  styleObjectToString(
-    {
-      ...(el.style || {}),
-      boxSizing: 'border-box',
-    },
-    unit
-  );
-
-const buildImageContentStyle = (
-  el: ImageElement,
-  unit: 'px' | 'rpx'
-): string => {
-  const style: Record<string, any> = { ...(el.style || {}) };
-  const borderWidth = Number(style.borderWidth);
-  if (Number.isFinite(borderWidth) && borderWidth > 0) {
-    if (!style.borderStyle) style.borderStyle = 'solid';
-    if (!style.borderColor) style.borderColor = '#000000';
-  }
-  return styleObjectToString(style, unit);
-};
-
-const buildTextIcon = (
-  el: TextElement,
-  unit: 'px' | 'rpx'
-): RenderNode['icon'] | undefined => {
-  const icon = el.icon;
-  if (!icon || icon.enable === false) return undefined;
-
-  const style = icon.style || 'fill';
-  const baseName = el.key || el.binding || el.id;
-  let name: string | undefined;
-  if (style === 'dot') name = 'round';
-  else if (style === 'line') name = baseName ? `${baseName}-line` : undefined;
-  else name = baseName || undefined;
-  if (!name) return undefined;
-
-  const size =
-    icon.size !== undefined && icon.size !== null
-      ? icon.size
-      : (el.style?.fontSize as any);
-  const gap =
-    icon.gap !== undefined && icon.gap !== null ? icon.gap : 4;
-  const color =
-    icon.color ??
-    ((typeof el.style?.color === 'string' ? el.style.color : undefined) as
-      | string
-      | undefined);
-
-  return {
-    name: `${name}`,
-    text: `${name}`,
-    size: addUnit(size as any, unit),
-    gap: addUnit(gap as any, unit),
-    color: color as any,
-    align: icon.align || 'left',
-    wrapperStyle: styleObjectToString(
-      {
-        display: 'inline-flex',
-        alignItems: 'center',
-        height: el.style?.lineHeight || 'auto',
-      },
-      unit
-    ),
-  };
-};
-
-/** ---------- 渲染树构建 ---------- */
-/**
- * 将 children 展开为渲染节点。
- */
-export const buildRenderNodes = (
-  children: CardElement[],
-  rootData: Record<string, any>,
-  unit: 'px' | 'rpx' = 'px',
-  context: BindingContext = {}
-): RenderNode[] => {
-  if (!Array.isArray(children)) return [];
-
-  const nodes: RenderNode[] = [];
-  children.forEach(el => {
-    if (!el || el.visible === false) return;
-    const node = buildNode(el, rootData, unit, context);
-    if (node) nodes.push(node);
-  });
-
-  return nodes;
-};
-/**
- * 构建单个渲染节点（layout-panel 递归处理子元素）。
- */
-const buildNode = (
-  el: CardElement,
-  rootData: Record<string, any>,
-  unit: 'px' | 'rpx',
-  context: BindingContext
-): RenderNode | null => {
-  if (!el || el.visible === false) return null;
-  const wrapperStyle = buildWrapperStyle(el, unit);
-
-  if (el.type === 'layout-panel') {
-    return {
-      id: el.id,
-      type: el.type,
-      visible: el.visible,
-      wrapperStyle,
-      contentStyle: buildPanelContentStyle(el as LayoutPanelElement, unit),
-      children: buildRenderNodes(el.children || [], rootData, unit, context),
-    };
-  }
-
-  const baseStyle = buildBaseContentStyle(el, unit);
-  if (el.type === 'text') {
-    const value =
-      resolveBindingValue(el.binding, rootData, context) ??
-      el.defaultValue ??
-      '';
-    return {
-      id: el.id,
-      type: el.type,
-      wrapperStyle,
-      contentStyle: buildTextContentStyle(el as TextElement, unit),
-      text: `${value}`,
-      visible: el.visible,
-      icon: buildTextIcon(el as TextElement, unit),
-    };
-  }
-
-  if (el.type === 'image') {
-    const src =
-      resolveBindingValue(el.binding, rootData, context) ??
-      (el as ImageElement).defaultUrl ??
-      el.defaultValue ??
-      '';
-    const mode =
-      (el as ImageElement).fit === 'contain' ? 'aspectFit' : 'aspectFill';
-    return {
-      id: el.id,
-      type: el.type,
-      wrapperStyle,
-      contentStyle: buildImageContentStyle(el as ImageElement, unit),
-      src,
-      mode,
-      visible: el.visible,
-    };
-  }
-
-  if (el.type === 'icon') {
-    const name =
-      resolveBindingValue(el.binding, rootData, context) ??
-      (el as IconElement).name ??
-      el.defaultValue ??
-      '';
-    return {
-      id: el.id,
-      type: el.type,
-      wrapperStyle,
-      contentStyle: baseStyle,
-      name: `${name}`,
-      text: `${name}`,
-      visible: el.visible,
-    };
-  }
-
-  if (el.type === 'custom') {
-    return {
-      id: el.id,
-      type: el.type,
-      wrapperStyle,
-      contentStyle: baseStyle,
-      visible: el.visible,
-    };
-  }
-
-  return null;
-};
-/**
- * 主入口：合并布局 Schema 与数据，生成供前端使用的渲染结果。
- */
-export const buildRenderResult = (
-  layoutInput: CardLayoutInput,
-  dataInput: Record<string, any>,
-  unit: 'px' | 'rpx' = 'px'
-): RenderResult => {
-  const layouts = normalizeLayout(layoutInput);
-  return layouts.map(layout => {
-    const cardStyle = buildCardStyle(layout, unit);
-    const bgStyle = buildBackgroundStyle(layout, unit);
-
-    const renderTree = buildRenderNodes(
-      layout.children || [],
-      dataInput || {},
-      unit
-    );
-
-    return {
-      renderTree,
-      cardStyle,
-      backgroundImage: layout.backgroundImage || '',
-      backgroundStyle: bgStyle,
-    };
-  });
-};
-
-export * from './utils';
+/**
+ * CardMaster 布局 JSON 渲染核心
+ *
+ * - 平台无关：不依赖 DOM/小程序 API，方便在 Web/小程序/Node 复用。
+ * - 职责：将布局 Schema 与业务数据合成可渲染树，外层只需将节点映射到各端组件。
+ */
+
+export * from './interface/index';
+export * from './helpers';
+export * from './layout';
+export * from './data';
+export * from './bindings';
+export {
+  backgroundChange,
+  DEFAULT_DECOR_COLOR,
+  resolveSpecialStyle,
+  applySpecialStyle,
+  applyBackground,
+  updateElementsStyle,
+} from './ops/changeBackground';
+export * from './render/builder';

package/layout.ts

@@ -0,0 +1,129 @@
+import type {
+  AbsoluteLayoutDefinition,
+  CardElement,
+  LayoutPanelElement,
+} from './interface/elements';
+import type { CardLayoutInput, CardLayoutSchema } from './interface/layout';
+import { toNumber, isObject } from './helpers';
+
+const DEFAULT_CARD_WIDTH = 343;
+const DEFAULT_CARD_HEIGHT = 210;
+
+export const roundToInt = (value: number): number =>
+  Number.isFinite(value) ? Math.round(value) : value;
+
+export const getAbsLayout = (
+  el: CardElement
+): AbsoluteLayoutDefinition | null =>
+  el.layout && el.layout.mode === 'absolute'
+    ? (el.layout as AbsoluteLayoutDefinition)
+    : null;
+
+const roundAbsLayout = (
+  layout: AbsoluteLayoutDefinition
+): AbsoluteLayoutDefinition => ({
+  ...layout,
+  x: roundToInt(layout.x),
+  y: roundToInt(layout.y),
+  width: roundToInt(layout.width),
+  height: roundToInt(layout.height),
+  zIndex:
+    layout.zIndex !== undefined ? roundToInt(layout.zIndex) : layout.zIndex,
+});
+
+export const sanitizeElement = (el: CardElement): CardElement => {
+  const layout = getAbsLayout(el);
+  const base = layout ? { ...el, layout: roundAbsLayout(layout) } : el;
+  if (el.type === 'layout-panel' && el.children) {
+    return {
+      ...(base as CardElement),
+      children: el.children.map(child => sanitizeElement(child)),
+    } as LayoutPanelElement;
+  }
+  return base;
+};
+
+export const sanitizeLayout = (layout: CardLayoutSchema): CardLayoutSchema => ({
+  ...layout,
+  width: roundToInt(layout.width),
+  height: roundToInt(layout.height),
+  backgroundZIndex:
+    layout.backgroundZIndex !== undefined
+      ? roundToInt(layout.backgroundZIndex)
+      : layout.backgroundZIndex,
+  children: (layout.children || []).map(child => sanitizeElement(child)),
+});
+
+export const collectBindings = (elements: CardElement[] = []): string[] => {
+  const result: string[] = [];
+  elements.forEach(el => {
+    if (el.binding) result.push(el.binding);
+    if (el.type === 'layout-panel' && el.children) {
+      result.push(...collectBindings(el.children));
+    }
+  });
+  return Array.from(new Set(result));
+};
+
+export const normalizeId = (id?: string | number | null) => {
+  if (id === undefined || id === null) return undefined;
+  const num = Number(id);
+  return Number.isFinite(num) ? num : id;
+};
+
+const safeParseJson = (input: string): any | null => {
+  try {
+    return JSON.parse(input);
+  } catch (err) {
+    console.warn('[km-card-layout-core] parseLayout failed', err);
+    return null;
+  }
+};
+
+const parseSingleLayout = (value: any): CardLayoutSchema | null => {
+  if (!value) return null;
+  if (Array.isArray(value)) return parseSingleLayout(value[0]);
+  if (typeof value === 'string') {
+    return parseSingleLayout(safeParseJson(value));
+  }
+  if (isObject(value)) {
+    const content = (value as any).content;
+    if (content !== undefined) {
+      const nested = parseSingleLayout(content);
+      if (nested) return nested;
+    }
+    return sanitizeLayout(value as CardLayoutSchema);
+  }
+  return null;
+};
+
+export const parseLayout = (input: unknown): CardLayoutSchema | null =>
+  parseSingleLayout(input);
+
+export const normalizeLayout = (
+  layout: CardLayoutInput
+): CardLayoutSchema[] => {
+  if (!Array.isArray(layout)) return [];
+  return layout
+    .map(item => {
+      if (!item || typeof item !== 'object') return null;
+      const parsed = item as CardLayoutSchema;
+      return {
+        ...parsed,
+        width: toNumber(parsed.width) ?? DEFAULT_CARD_WIDTH,
+        height: toNumber(parsed.height) ?? DEFAULT_CARD_HEIGHT,
+        container: (parsed as any).container || { mode: 'absolute' },
+        children: Array.isArray((parsed as any).children)
+          ? ((parsed as any).children as CardElement[])
+          : [],
+      };
+    })
+    .filter((value): value is CardLayoutSchema => Boolean(value));
+};
+
+export const areChildrenEqual = (
+  a?: CardLayoutSchema | null,
+  b?: CardLayoutSchema | null
+): boolean => {
+  return JSON.stringify(a?.children) === JSON.stringify(b?.children);
+};