km-card-layout-core 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# km-card-layout-core
+
+纯函数渲染核心：负责将布局 JSON 与数据合成渲染树，处理绑定路径、repeatable-group 展开、样式单位（px/rpx）等。
+
+## API
+
+- `normalizeLayout(layout)`：清洗/容错布局对象或 JSON 字符串，补齐默认尺寸/children。
+- `buildRenderResult(layout, data, unit?)`：返回 `{ renderTree, cardStyle, backgroundImage, backgroundStyle }`，可直接用于 PC/Vue、小程序等多端。
+- `buildRenderNodes(children, data, unit?, context?)`：仅展开 children 为渲染节点列表。
+- 其他工具：`resolveBindingValue`（绑定读取，支持 `$item.` 与 dataPath 上下文）、`styleObjectToString`、`addUnit`。
+
+## 适用场景
+
+- PC 端：在 Vue 组件里调用 `buildRenderResult`，把 renderTree 映射为 VDOM。
+- 小程序：被 `km-card-layout-component-miniprogram` 依赖，组件中通过 core 得到 renderTree。
+- 预渲染/快照：Node 环境按相同逻辑生成渲染树后做静态输出或图片化。
+
+核心不依赖 DOM/平台 API，可直接通过 `require('km-card-layout-core')` 使用。

package/dist/index.js

@@ -0,0 +1,524 @@
+"use strict";
+/**
+ * CardMaster 布局 JSON 渲染核心。
+ *
+ * - 平台无关：不依赖 DOM/小程序 API，方便在 Web/小程序/Node 复用。
+ * - 职责：将布局 Schema 与业务数据合成为带内联样式的渲染树，外层只需将节点映射到各端组件。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRenderResult = exports.buildRenderNodes = exports.resolveBindingValue = exports.normalizeLayout = exports.styleObjectToString = exports.addUnit = void 0;
+__exportStar(require("./interface"), exports);
+/** ---------- 常量 ---------- */
+const DEFAULT_CARD_WIDTH = 343; // 默认卡片宽度（像素）
+const DEFAULT_CARD_HEIGHT = 210; // 默认卡片高度（像素）
+const DEFAULT_GROUP_GAP = 22; // repeatable-item 默认纵向间距
+const DIMENSION_PROPS = new Set([
+    '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) => {
+    const num = Number(value);
+    return Number.isFinite(num) ? num : undefined;
+};
+/**
+ * camelCase 转 kebab-case（用于内联样式 key）。
+ */
+const toKebab = (key) => key.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+/**
+ * 数字追加单位，非数字原样转字符串。
+ * 数字追加单位，非数字原样转字符串。
+ */
+const addUnit = (value, unit) => {
+    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}`;
+};
+exports.addUnit = addUnit;
+/**
+ * 样式对象转内联样式字符串，对需要单位的字段自动补单位。
+ */
+const styleObjectToString = (style, unit = 'px') => {
+    if (!style)
+        return '';
+    const pairs = [];
+    Object.keys(style).forEach(key => {
+        const value = style[key];
+        if (value === undefined || value === null || value === '')
+            return;
+        const useUnit = DIMENSION_PROPS.has(key)
+            ? (0, exports.addUnit)(value, unit)
+            : value;
+        if (useUnit === undefined || useUnit === null || useUnit === '')
+            return;
+        pairs.push(`${toKebab(key)}:${useUnit}`);
+    });
+    return pairs.join(';');
+};
+exports.styleObjectToString = styleObjectToString;
+/**
+ * 容错 JSON 解析：字符串用 JSON.parse，其他保持原样或返回 null。
+ */
+const parseJson = (input) => {
+    if (typeof input !== 'string')
+        return input !== null && input !== void 0 ? input : null;
+    try {
+        return JSON.parse(input);
+    }
+    catch (err) {
+        console.warn('[km-card-layout-core] JSON parse failed', err);
+        return null;
+    }
+};
+const isObject = (val) => Boolean(val) && typeof val === 'object';
+const getAbsLayout = (el) => el.layout && el.layout.mode === 'absolute'
+    ? el.layout
+    : null;
+const getFlexLayout = (el) => el.layout && el.layout.mode === 'flex'
+    ? el.layout
+    : null;
+/** ---------- 布局与数据解析 ---------- */
+/**
+ * 归一化布局输入（对象或 JSON 字符串），补齐宽高/容器/children 默认值。
+ */
+const normalizeLayout = (layout) => {
+    if (!Array.isArray(layout))
+        return [];
+    return layout
+        .map(item => {
+        var _a, _b;
+        if (!item || typeof item !== 'object')
+            return null;
+        const parsed = item;
+        return {
+            ...parsed,
+            width: (_a = toNumber(parsed.width)) !== null && _a !== void 0 ? _a : DEFAULT_CARD_WIDTH,
+            height: (_b = toNumber(parsed.height)) !== null && _b !== void 0 ? _b : DEFAULT_CARD_HEIGHT,
+            container: parsed.container || { mode: 'absolute' },
+            children: Array.isArray(parsed.children)
+                ? parsed.children
+                : [],
+        };
+    })
+        .filter((v) => Boolean(v));
+};
+exports.normalizeLayout = normalizeLayout;
+/**
+ * 将绑定路径拆分为片段，支持点语法与数组下标。
+ */
+const pathToSegments = (path) => `${path || ''}`
+    .replace(/\[(\d+)\]/g, '.$1')
+    .split('.')
+    .map(p => p.trim())
+    .filter(Boolean);
+/**
+ * 按路径访问对象/数组，缺失时返回 undefined/null。
+ */
+const readByPath = (data, path) => {
+    if (path === undefined || path === null || path === '')
+        return data;
+    const segments = pathToSegments(path);
+    let cursor = 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[key];
+        }
+        if (cursor === undefined || cursor === null) {
+            return cursor;
+        }
+    }
+    return cursor;
+};
+/**
+ * 解析元素 binding 对应的数据：
+ * - 全局 binding：直接基于根数据；
+ * - repeatable-group：binding 等于/前缀 dataPath 或以 `$item.` 开头时，改用当前条目数据。
+ */
+const resolveBindingValue = (binding, rootData, context) => {
+    if (!binding)
+        return undefined;
+    const { contextBinding, contextData } = context || {};
+    let target = 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;
+};
+exports.resolveBindingValue = resolveBindingValue;
+/** ---------- 样式构建 ---------- */
+/**
+ * 生成元素外层样式（绝对/弹性布局），始终返回内联样式字符串。
+ */
+const buildWrapperStyle = (el, unit) => {
+    var _a, _b;
+    const abs = getAbsLayout(el);
+    if (abs) {
+        const textAlign = (_a = el === null || el === void 0 ? void 0 : el.style) === null || _a === void 0 ? void 0 : _a.textAlign;
+        return (0, exports.styleObjectToString)({
+            position: 'absolute',
+            left: (0, exports.addUnit)(abs.x, unit),
+            top: (0, exports.addUnit)(abs.y, unit),
+            width: (0, exports.addUnit)(abs.width, unit),
+            height: (0, exports.addUnit)(abs.height, unit),
+            zIndex: abs.zIndex,
+            boxSizing: 'border-box',
+            textAlign,
+        }, unit);
+    }
+    const flex = getFlexLayout(el);
+    if (!flex)
+        return '';
+    const item = flex.item || {};
+    return (0, exports.styleObjectToString)({
+        width: (0, exports.addUnit)(flex.width, unit),
+        height: (0, exports.addUnit)(flex.height, unit),
+        order: item.order,
+        flexGrow: item.flexGrow,
+        flexShrink: item.flexShrink,
+        flexBasis: item.flexBasis,
+        alignSelf: item.alignSelf,
+        boxSizing: 'border-box',
+        textAlign: (_b = el === null || el === void 0 ? void 0 : el.style) === null || _b === void 0 ? void 0 : _b.textAlign,
+    }, unit);
+};
+/**
+ * padding 数组/数字转 CSS 缩写字符串。
+ */
+const formatPadding = (padding, unit) => {
+    if (padding === undefined || padding === null)
+        return undefined;
+    if (typeof padding === 'number')
+        return (0, exports.addUnit)(padding, unit);
+    if (Array.isArray(padding)) {
+        const list = padding
+            .filter(v => v !== undefined && v !== null)
+            .map(v => (0, exports.addUnit)(v, 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, unit) => {
+    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, unit),
+    };
+    if (options.gap && typeof options.gap === 'number') {
+        style.gap = (0, exports.addUnit)(options.gap, unit);
+    }
+    else if (options.gap && isObject(options.gap)) {
+        style.rowGap = (0, exports.addUnit)(options.gap.row, unit);
+        style.columnGap = (0, exports.addUnit)(options.gap.column, unit);
+    }
+    return (0, exports.styleObjectToString)(style, unit);
+};
+/**
+ * 元素样式转内联字符串（自动补单位）。
+ */
+const normalizeElementStyle = (style, unit) => {
+    if (!style)
+        return '';
+    return (0, exports.styleObjectToString)(style, unit);
+};
+/** ---------- Repeatable 相关 ---------- */
+/**
+ * 通过前两条 item 的布局推断间距，不足则回落 DEFAULT_GROUP_GAP。
+ */
+const inferGroupGap = (group) => {
+    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, rootData) => {
+    const result = [];
+    const dataset = (0, exports.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 },
+                }
+                : el;
+            result.push({
+                element: cloned,
+                contextData: payload,
+                contextBinding: group.dataPath,
+            });
+        });
+    });
+    return result;
+};
+/** ---------- 渲染树构建 ---------- */
+/**
+ * 将 children 展开为渲染节点，处理 repeatable-group 展开与 mutualExcludes 隐藏。
+ */
+const buildRenderNodes = (children, rootData, unit = 'px', context = {}) => {
+    if (!Array.isArray(children))
+        return [];
+    // Mark mutually exclusive bindings to hide them when repeatable-group is present
+    const excluded = new Set();
+    children.forEach(el => {
+        if (el && el.type === 'repeatable-group' && !!el.visible) {
+            (el.mutualExcludes || []).forEach(b => excluded.add(b));
+        }
+    });
+    const nodes = [];
+    children.forEach(el => {
+        if (!el || el.visible === false)
+            return;
+        if (el.type === 'repeatable-group') {
+            const instances = materializeRepeatableItems(el, 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;
+};
+exports.buildRenderNodes = buildRenderNodes;
+/**
+ * 构建单个渲染节点（layout-panel 递归处理子元素）。
+ */
+const buildNode = (el, rootData, unit, context) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    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, unit),
+            children: (0, exports.buildRenderNodes)(el.children || [], rootData, unit, context),
+        };
+    }
+    const baseStyle = normalizeElementStyle(el.style, unit);
+    if (el.type === 'text') {
+        const align = ((_a = el.style) === null || _a === void 0 ? void 0 : _a.textAlign) || el.align;
+        const textStyle = align ? `${baseStyle};text-align:${align}` : baseStyle;
+        const value = (_c = (_b = (0, exports.resolveBindingValue)(el.binding, rootData, context)) !== null && _b !== void 0 ? _b : el.defaultValue) !== null && _c !== void 0 ? _c : '';
+        return {
+            id: el.id,
+            type: el.type,
+            wrapperStyle,
+            contentStyle: textStyle,
+            text: `${value}`,
+            visible: !!el.visible,
+        };
+    }
+    if (el.type === 'image') {
+        const src = (_f = (_e = (_d = (0, exports.resolveBindingValue)(el.binding, rootData, context)) !== null && _d !== void 0 ? _d : el.defaultUrl) !== null && _e !== void 0 ? _e : el.defaultValue) !== null && _f !== void 0 ? _f : '';
+        const mode = el.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 = (_j = (_h = (_g = (0, exports.resolveBindingValue)(el.binding, rootData, context)) !== null && _g !== void 0 ? _g : el.name) !== null && _h !== void 0 ? _h : el.defaultValue) !== null && _j !== void 0 ? _j : '';
+        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 与数据，生成供前端使用的渲染结果。
+ */
+const buildRenderResult = (layoutInput, dataInput, unit = 'px') => {
+    const layouts = (0, exports.normalizeLayout)(layoutInput);
+    return layouts.map(layout => {
+        const cardStyle = (0, exports.styleObjectToString)({
+            width: (0, exports.addUnit)(layout.width, unit),
+            height: (0, exports.addUnit)(layout.height, unit),
+            color: layout.fontColor,
+            borderRadius: layout.borderRadius !== undefined
+                ? (0, exports.addUnit)(layout.borderRadius, unit)
+                : undefined,
+            padding: layout.padding !== undefined
+                ? (0, exports.addUnit)(layout.padding, unit)
+                : undefined,
+            position: 'relative',
+        }, unit);
+        const bgStyle = (0, exports.styleObjectToString)({
+            zIndex: layout.backgroundZIndex,
+            borderRadius: layout.borderRadius !== undefined
+                ? (0, exports.addUnit)(layout.borderRadius, unit)
+                : undefined,
+        }, unit);
+        const renderTree = (0, exports.buildRenderNodes)(layout.children || [], dataInput || {}, unit);
+        return {
+            renderTree,
+            cardStyle,
+            backgroundImage: layout.backgroundImage || '',
+            backgroundStyle: bgStyle,
+        };
+    });
+};
+exports.buildRenderResult = buildRenderResult;
+__exportStar(require("./utils"), exports);

package/dist/interface/data/payload.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interface/elements.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interface/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./elements"), exports);
+__exportStar(require("./layout"), exports);
+__exportStar(require("./render"), exports);

package/dist/interface/layout.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interface/render.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backgroundChange = backgroundChange;
+function backgroundChange(bg, layout) {
+    const toNameArray = (name) => {
+        if (Array.isArray(name))
+            return name.filter(Boolean);
+        if (!name)
+            return [];
+        return `${name}`
+            .split(',')
+            .map(n => n.trim())
+            .filter(Boolean);
+    };
+    const applySpecialColor = (el) => {
+        const extras = bg.fontColorExtra || [];
+        if (!extras.length)
+            return el;
+        const keys = [];
+        if (el.binding)
+            keys.push(String(el.binding));
+        if (el.id)
+            keys.push(String(el.id));
+        if (el.type === 'icon')
+            keys.push('icon');
+        if (el.type === 'custom')
+            keys.push('decor');
+        const matched = extras.find(sc => toNameArray(sc.name).some(n => keys.some(k => k === null || k === void 0 ? void 0 : k.startsWith(n))));
+        if (!matched)
+            return el;
+        const baseStyle = { ...(el.style || {}) };
+        if (el.type === 'custom') {
+            return { ...el, style: { ...baseStyle, backgroundColor: matched.color } };
+        }
+        return { ...el, style: { ...baseStyle, color: matched.color } };
+    };
+    const traverse = (children = []) => children.map(el => {
+        if (!el)
+            return el;
+        if (el.type === 'layout-panel') {
+            return {
+                ...el,
+                children: traverse(el.children || []),
+            };
+        }
+        if (el.type === 'repeatable-group') {
+            return {
+                ...el,
+                itemTemplate: traverse(el.itemTemplate || []),
+                items: (el.items || []).map(item => ({
+                    ...item,
+                    elements: traverse(item.elements || []),
+                })),
+            };
+        }
+        return applySpecialColor(el);
+    });
+    return {
+        ...layout,
+        backgroundImage: bg.imgUrl,
+        fontColor: bg.fontColor || layout.fontColor,
+        children: traverse(layout.children || []),
+    };
+}