卡片开发规范

在魔方系统中，一个完整的业务组件由 视图卡组件 和 编辑卡组件 两个部分组成。

视图卡组件

魔方页面渲染视图卡组件时将会传入 confData 与 isDesktop 参数。开发者可根据 confData 中的数据渲染视图卡组件。

代码示例

src/lib/view/index.tsx
import React from 'react';

type TProps = {
  confData: any; // 根据业务数据定义类型
  isDesktop: boolean;
};

const ViewCard: React.FC<TProps> = ({ confData, isDesktop }) => {
  retrun <div>卡片内容</div>;
}

ViewCard.displayName = 'ViewCard';

export default ViewCard;

参数说明

confData：包含卡片的所有配置数据
isDesktop：当前环境是否为 PC 端，魔方支持多端展示，配合图片裁切功能可保证多端图片显示效果最佳。

设计稿及尺寸单位

设计稿：建议： 开发魔方卡片时设计师可以用 iPhone6 作为视觉稿的标准。
尺寸单位：px2rem(375) = 视口宽度

使用方法如下：

src/lib/view/index.module.scss
@import '../../styles/_mixin.scss';

.card {
  width: px2rem(375);
  height: px2rem(200);
}

体验优化

视图组件推荐打包后的尺寸 小于 160KB
React, axios已内置，推荐使用 axios 作为默认请求库减少包体积
swiper 建议使用版本为 "^8.4.5"，与魔方框架保持一致
推荐设置组件最小高度，避免组件初始化阶段导致的页面抖动（详见骨架图章节）

编辑卡组件

魔方页面渲染编辑卡组件时将会传入 confData、dispatch、isDarkMode 参数，开发者可根据 confData 中的数据渲染编辑卡组件, 使用 dispatch 修改 confData 中的数据。

代码示例

src/lib/edit/index.tsx
import React from 'react';

type TProps = {
  confData: any; // 根据业务数据定义类型
  isDarkMode: boolean; // 是否为深色模式
  dispatch: React.Dispatch<any>; // 与魔方编辑器进行数据交互的方法v
};

const EditCard: React.FC<TProps> = ({ confData, dispatch, isDarkMode }) => {
  retrun <div>卡片内容</div>;
}

EditCard.displayName = 'EditCard';

export default EditCard;

参数说明

confData 包含卡片的所有配置数据
isDarkMode 判断魔方编辑器是否为深色模式
dispatch 与魔方编辑器进行数据交互的方法

数据更新

魔方编辑器 store 状态管理基于 immer.js 设计，简化了不可变数据结构的处理，我们假设 confData.data.text 为卡片的文本数据，通过 dispatch 更新该字段数据：

编辑卡实现

src/lib/edit/index.tsx
import React from 'react';

type TProps = {
  confData: any; // 根据业务数据定义类型
  isDarkMode: boolean; // 是否为深色模式
  dispatch: React.Dispatch<any>; // 与魔方编辑器进行数据交互的方法
};

const EditCard: React.FC<TProps> = ({ confData, dispatch }) => {
  const changeText = useCallback(() => {
    dispatch({
      type: 'UPDATE_MODULE',
      payload(draft: any) {
        draft.data.text = Math.random();
      },
    });
  });
  retrun(
    <button type="button" onClick={changeText}>
      点击测试状态变更
    </button>,
  );
};

EditCard.displayName = 'EditCard';

export default EditCard;

视图卡实现

src/lib/view/index.tsx
import React from 'react';

type TProps = {
  confData: any; // 根据业务数据定义类型
  isDesktop: boolean;
};

const ViewCard: React.FC<TProps> = ({ confData, isDesktop }) => {
  retrun <div>{confData.data.text}</div>;
}

ViewCard.displayName = 'ViewCard';

export default ViewCard;

信息

在模块商店的卡片开发中固定使用 type 为 UPDATE_MODULE 的 dispatch 方法。

深色模式

魔方编辑器支持深色模式，开发的编辑卡也需要适配深色模式，可以通过以下两种方式适配：

通过 isDarkMode 判断是否为深色模式

src/lib/edit/index.tsx
import React from 'react';

type TProps = {
  confData: any;
  isDarkMode: boolean; // 是否为深色模式
  dispatch: React.Dispatch<any>;
};

const EditCard: React.FC<TProps> = ({ confData, dispatch, isDarkMode }) => {
  retrun <div className={isDarkMode ? 'dark' : ''}>卡片内容</div>;
}

EditCard.displayName = 'EditCard';

export default EditCard;

通过 body 样式类名 theme-dark 判断是否为深色模式

src/lib/edit/index.module.scss
:global(.theme-dark) {
  .xxx {
    background-color: #000;
  }
}

confData 数据结构

confData 是一个卡片的数据结构，下面是一个卡片的基本结构：

{
  "id": 143718,
  "name": "cardHtml",
  "topicId": 3890,
  "componentId": 0,
  "starttime": "",
  "endtime": "",
  "data": {
    "style": "",
    "getType": "0",
    "notes": "自定义样式",
    "customTheme": "",
    "html": "",
    "lastModified": 1695192702512,
    "modifiedUser": "mimengyu"
  },
  "biz": "",
  "bizSub": "",
  "customData": {
    "timeRangeType": "0",
    "bizType": "0",
    "class": "",
    "platform": "all",
    "cityValue": []
  },
  "ordernum": 5,
  "enabled": true,
  "isModified": 0,
  "createdUser": "mimengyu",
  "remark": ""
}

字段详解说明查看内置能力章节。

defaultData.json 配置

卡片初始化阶段将 defaultData.json 中的数据合并到 confData 字段中作为组件的 prop 值传入。

defaultData.json 数据格式如下，使用 data 字段定义业务数据。

src/lib/defaultData.json
{
  "data": {
    "title": "这是一个标题",
    "content": "这是一个内容"
  }
}

信息

你需要在 defaultData.json 中配置所有视图卡中消费的数据，这有助于视图卡和编辑卡之间的数据同步。因为卡片间通过 immerjs + 状态管理同步状态，需遵循 immer 更新模式。

关于限制

图片资源应采用外联方式引入，不要使用 import 方式，库模式对资源相对路径解析限制
异步组件方式慎用，路径解析限制，建议使用同步方式（注：异步脚本不受影响）
推荐使用 CSS Modules 方式开发样式（选择其他工具的开发者需自行解决作用域问题，避免样式冲突）

卡片开发规范

视图卡组件​

代码示例​

参数说明​

设计稿及尺寸单位​

体验优化​

编辑卡组件​

代码示例​

参数说明​

数据更新​

深色模式​

confData 数据结构​

defaultData.json 配置​

关于限制​

视图卡组件

代码示例

参数说明

设计稿及尺寸单位

体验优化

编辑卡组件

代码示例

参数说明

数据更新

深色模式

confData 数据结构

defaultData.json 配置

关于限制