km-card-layout-core 0.1.0

package/index.ts

@@ -0,0 +1,614 @@
+/**
+ * CardMaster 布局 JSON 渲染核心。
+ *
+ * - 平台无关：不依赖 DOM/小程序 API，方便在 Web/小程序/Node 复用。
+ * - 职责：将布局 Schema 与业务数据合成为带内联样式的渲染树，外层只需将节点映射到各端组件。
+ */
+
+import type {
+  AbsoluteLayoutDefinition,
+  CardElement,
+  CardElementType,
+  FlexItemLayoutDefinition,
+  IconElement,
+  ImageElement,
+  LayoutPanelElement,
+  RepeatableGroupElement,
+} from './interface/elements';
+import type { CardLayoutInput, CardLayoutSchema } from './interface/layout';
+import type {
+  BindingContext,
+  RenderNode,
+  RenderPageResult,
+  RenderResult,
+} from './interface/render';
+
+export * from './interface';
+
+/** ---------- 常量 ---------- */
+
+const DEFAULT_CARD_WIDTH = 343; // 默认卡片宽度（像素）
+const DEFAULT_CARD_HEIGHT = 210; // 默认卡片高度（像素）
+const DEFAULT_GROUP_GAP = 22; // repeatable-item 默认纵向间距
+
+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',
+  'flexBasis',
+]);
+
+/** ---------- 基础工具 ---------- */
+/**
+ * 安全转 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;
+
+const getFlexLayout = (el: CardElement): FlexItemLayoutDefinition | null =>
+  el.layout && el.layout.mode === 'flex'
+    ? (el.layout as FlexItemLayoutDefinition)
+    : 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;
+};
+/**
+ * 解析元素 binding 对应的数据：
+ * - 全局 binding：直接基于根数据；
+ * - repeatable-group：binding 等于/前缀 dataPath 或以 `$item.` 开头时，改用当前条目数据。
+ */
+export const resolveBindingValue = (
+  binding: string | undefined,
+  rootData: Record<string, any>,
+  context?: BindingContext
+): any => {
+  if (!binding) return undefined;
+  const { contextBinding, contextData } = context || {};
+  let target: any = rootData;
+  let path = binding;
+
+  // repeatable-group: binding 等于 dataPath 或以其为前缀时，切换到当前条目数据
+  if (
+    contextBinding &&
+    (binding === contextBinding || binding.startsWith(`${contextBinding}.`))
+  ) {
+    target = contextData;
+    path =
+      binding === contextBinding
+        ? ''
+        : binding.slice(contextBinding.length + 1);
+  } else if (binding.startsWith('$item.')) {
+    target = contextData;
+    path = binding.slice('$item.'.length);
+  }
+
+  const value = readByPath(target, path);
+  return value === undefined ? undefined : value;
+};
+
+/** ---------- 样式构建 ---------- */
+
+/**
+ * 生成元素外层样式（绝对/弹性布局），始终返回内联样式字符串。
+ */
+const buildWrapperStyle = (el: CardElement, unit: 'px' | 'rpx'): string => {
+  const abs = getAbsLayout(el);
+  if (abs) {
+    const textAlign = el?.style?.textAlign as string | undefined;
+    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',
+        textAlign,
+      },
+      unit
+    );
+  }
+
+  const flex = getFlexLayout(el);
+  if (!flex) return '';
+  const item:any = flex.item || {};
+  return styleObjectToString(
+    {
+      width: addUnit(flex.width, unit),
+      height: addUnit(flex.height, unit),
+      order: item.order,
+      flexGrow: item.flexGrow,
+      flexShrink: item.flexShrink,
+      flexBasis: item.flexBasis,
+      alignSelf: item.alignSelf,
+      boxSizing: 'border-box',
+      textAlign: el?.style?.textAlign as string | undefined,
+    },
+    unit
+  );
+};
+/**
+ * padding 数组/数字转 CSS 缩写字符串。
+ */
+const formatPadding = (
+  padding: number | number[] | undefined,
+  unit: 'px' | 'rpx'
+) => {
+  if (padding === undefined || padding === null) return undefined;
+  if (typeof padding === 'number') return addUnit(padding, unit);
+  if (Array.isArray(padding)) {
+    const list = padding
+      .filter(v => v !== undefined && v !== null)
+      .map(v => addUnit(v as number, unit));
+    if (!list.length) return undefined;
+    if (list.length === 2) return `${list[0]} ${list[1]}`;
+    if (list.length === 3) return `${list[0]} ${list[1]} ${list[2]}`;
+    if (list.length >= 4) return `${list[0]} ${list[1]} ${list[2]} ${list[3]}`;
+  }
+  return undefined;
+};
+/**
+ * 构建 layout-panel 的容器样式（flex）。
+ */
+const buildPanelStyle = (
+  el: LayoutPanelElement,
+  unit: 'px' | 'rpx'
+): string => {
+  const options = (el.container && el.container.options) || {};
+  const style = {
+    display: 'flex',
+    flexDirection: options.direction || 'row',
+    flexWrap: options.wrap || 'nowrap',
+    justifyContent: options.justifyContent,
+    alignItems: options.alignItems,
+    padding: formatPadding(options.padding as any, unit),
+  } as Record<string, any>;
+
+  if (options.gap && typeof options.gap === 'number') {
+    style.gap = addUnit(options.gap, unit);
+  } else if (options.gap && isObject(options.gap)) {
+    style.rowGap = addUnit((options.gap as any).row, unit);
+    style.columnGap = addUnit((options.gap as any).column, unit);
+  }
+
+  return styleObjectToString(style, unit);
+};
+/**
+ * 元素样式转内联字符串（自动补单位）。
+ */
+const normalizeElementStyle = (
+  style: Record<string, any> | undefined,
+  unit: 'px' | 'rpx'
+): string => {
+  if (!style) return '';
+  return styleObjectToString(style, unit);
+};
+
+/** ---------- Repeatable 相关 ---------- */
+/**
+ * 通过前两条 item 的布局推断间距，不足则回落 DEFAULT_GROUP_GAP。
+ */
+const inferGroupGap = (group: RepeatableGroupElement): number => {
+  const items = group.items || [];
+  if (items.length >= 2) {
+    const first = (items[0].elements || []).map(getAbsLayout).find(Boolean);
+    const second = (items[1].elements || []).map(getAbsLayout).find(Boolean);
+    if (
+      first &&
+      second &&
+      typeof first.y === 'number' &&
+      typeof second.y === 'number'
+    ) {
+      return Math.abs(second.y - first.y);
+    }
+  }
+  return DEFAULT_GROUP_GAP;
+};
+/**
+ * 展开 repeatable-group 为具体元素实例，并附带条目数据。
+ * 优先使用设计器保存的 `items`；否则按推断间距克隆 `itemTemplate`。
+ */
+const materializeRepeatableItems = (
+  group: RepeatableGroupElement,
+  rootData: Record<string, any>
+): { element: CardElement; contextData: any; contextBinding: string }[] => {
+  const result: {
+    element: CardElement;
+    contextData: any;
+    contextBinding: string;
+  }[] = [];
+  const dataset = resolveBindingValue(group.dataPath, rootData, {}) || [];
+  const dataList = Array.isArray(dataset) ? dataset : [];
+  const maxItems =
+    group.maxItems ||
+    dataList.length ||
+    (group.items || []).length ||
+    (group.itemTemplate || []).length;
+  const template =
+    (group.items && group.items[0] && group.items[0].elements) ||
+    group.itemTemplate ||
+    [];
+  const gap = inferGroupGap(group);
+
+  // Use saved items (from designer) first
+  if (group.items && group.items.length) {
+    group.items.slice(0, maxItems).forEach((item, idx) => {
+      const payload = dataList[idx] !== undefined ? dataList[idx] : item.data;
+      (item.elements || []).forEach(el => {
+        result.push({
+          element: el,
+          contextData: payload,
+          contextBinding: group.dataPath,
+        });
+      });
+    });
+    return result;
+  }
+
+  // Otherwise clone from template by gap
+  dataList.slice(0, maxItems).forEach((payload, idx) => {
+    template.forEach(el => {
+      const abs = getAbsLayout(el);
+      const cloned = abs
+        ? ({
+            ...el,
+            layout: { ...abs, y: abs.y + idx * gap },
+          } as CardElement)
+        : el;
+      result.push({
+        element: cloned,
+        contextData: payload,
+        contextBinding: group.dataPath,
+      });
+    });
+  });
+
+  return result;
+};
+
+/** ---------- 渲染树构建 ---------- */
+/**
+ * 将 children 展开为渲染节点，处理 repeatable-group 展开与 mutualExcludes 隐藏。
+ */
+export const buildRenderNodes = (
+  children: CardElement[],
+  rootData: Record<string, any>,
+  unit: 'px' | 'rpx' = 'px',
+  context: BindingContext = {}
+): RenderNode[] => {
+  if (!Array.isArray(children)) return [];
+
+  // Mark mutually exclusive bindings to hide them when repeatable-group is present
+  const excluded = new Set<string>();
+  children.forEach(el => {
+    if (el && el.type === 'repeatable-group' && !!el.visible) {
+      (el.mutualExcludes || []).forEach(b => excluded.add(b));
+    }
+  });
+
+  const nodes: RenderNode[] = [];
+  children.forEach(el => {
+    if (!el || el.visible === false) return;
+    if (el.type === 'repeatable-group') {
+      const instances = materializeRepeatableItems(
+        el as RepeatableGroupElement,
+        rootData
+      );
+      instances.forEach(({ element, contextData, contextBinding }) => {
+        const node = buildNode(element, rootData, unit, {
+          ...context,
+          contextData,
+          contextBinding,
+        });
+        if (node) nodes.push(node);
+      });
+      return;
+    }
+
+    if (el.binding && excluded.has(el.binding)) 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: buildPanelStyle(el as LayoutPanelElement, unit),
+      children: buildRenderNodes(el.children || [], rootData, unit, context),
+    };
+  }
+
+  const baseStyle = normalizeElementStyle(el.style, unit);
+  if (el.type === 'text') {
+    const align = (el.style?.textAlign as string | undefined) || el.align;
+    const textStyle = align ? `${baseStyle};text-align:${align}` : baseStyle;
+    const value =
+      resolveBindingValue(el.binding, rootData, context) ??
+      el.defaultValue ??
+      '';
+    return {
+      id: el.id,
+      type: el.type,
+      wrapperStyle,
+      contentStyle: textStyle,
+      text: `${value}`,
+      visible: !!el.visible,
+    };
+  }
+
+  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: baseStyle,
+      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,
+    };
+  }
+
+  // Unknown type fallback to simple text node
+  return {
+    id: el.id,
+    type: 'text',
+    wrapperStyle,
+    contentStyle: baseStyle,
+    text: el.defaultValue || '',
+    visible: !!el.visible,
+  };
+};
+/**
+ * 主入口：合并布局 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 = 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',
+      },
+      unit
+    );
+    const bgStyle = styleObjectToString(
+      {
+        zIndex: layout.backgroundZIndex,
+        borderRadius:
+          layout.borderRadius !== undefined
+            ? addUnit(layout.borderRadius, unit)
+            : undefined,
+      },
+      unit
+    );
+
+    const renderTree = buildRenderNodes(
+      layout.children || [],
+      dataInput || {},
+      unit
+    );
+
+    return {
+      renderTree,
+      cardStyle,
+      backgroundImage: layout.backgroundImage || '',
+      backgroundStyle: bgStyle,
+    };
+  });
+};
+
+
+export * from './utils'

package/interface/data/payload.ts

@@ -0,0 +1,24 @@
+/**
+ * 背景项
+ */
+export interface TemplateBackground {
+  id: number;
+  name: string;
+  fileId?: number;
+  fontColor?: string;
+  fontColorExtra?: { name: string | string[]; color: string }[]
+  imgUrl: string;
+}
+
+
+/**
+ * 元素项
+ */
+export interface TemplateItem {
+  id: number;
+  name: string;
+  bind: string;
+  default?: string;
+  type: 'text' | 'image';
+  cate: number;
+}