sds-design-sdk

SDK 安装

NPM Package

通过 npm 或 yarn 安装并引入 sds-design-sdk

npm install sds-design-sdk

yarn add sds-design-sdk

CSS 字体预声明

方法一：在你项目的设计器代码头部中引入

import 'sds-design-sdk/dist/fonts.css';

方法二：在你项目的全局样式文件中引入，注意不要被其他样式覆盖

/* 例如在 global.css 中 */
@import '~sds-design-sdk/dist/fonts.css';

SDK 初始化

import { SdsDesign } from 'sds-design-sdk';

const sdk = new SdsDesign();
sdk.init({
  appId: 'xxxxx',
  secret: 'xxxxx',
  timestamp: 1654591844051,
  productId: '28047',
  previewContainerId: 'previewBox',
  previewSize: 240,
  designContainerId: 'designBox',
  syncMode: 'sync',
  initCallback: () => {},
  designCallback: (data) => { console.log(data); },
});

init 参数说明

| 参数 | 类型 | 说明 | 必填/选填 | | ------------------ | -------- | ------------------------ | -------------- | | appId | string | 应用 ID，由 SDS 平台提供 | 必填 | | secret | string | 应用开发密钥，由 SDS 平台提供 | 必填 | | timestamp | number | 时间戳 | 必填 | | language | string | 使用的语言（zh-CN、en-US） | 选填，默认值：'zh-CN' | | productId | string | 产品 ID | 必填 | | previewContainerId | string | 预览图的容器节点 ID，不需要额外写 # 号 | 必填 | | previewSize | number | 预览图的显示尺寸 | 选填，默认值：1000 | | designContainerId | string | 设计画布的容器节点 ID，不需要额外写 # 号 | 必填 | | syncMode | string | 生成设计成品的模式（sync、async） | 选填，默认值：'sync' | | initCallback | function | SDK初始化后回调 | 选填 | | designCallback | function | 设计画布的操作回调，每次操作画布都会触发 | 必填 |

designCallback 返回值数据结构

每次操作设计画布时，都会触发该回调，一般用于即时获取设计画布的图层信息、历史记录等设计数据

{
  "layers": [ // 设计画布的图层信息
    {
      "type": "i-text", // image:图片图层 / i-text:文本图层 / group: 图层组
      "fontFamily": "Arial",
      "fontSize": 30
      "text": "Hello World",
    }, {
      "type": "group"
      "objects": [
        {
          "type": "image",
          "left": 300,
          "top": 300,
          "width": 720,
          "height": 720,
          "angle": 0,
        }
      ]
    }
  ]
  "index": "number", // 当前选中的画布图层 index，
  "history": "string[]", // 设计历史记录数组，存储最近十次操作，数组项为 json
  "historyIndex": "number", // 当前使用的设计历史记录 index，还原和回退历史操作的时候使用
  "updatePreview": "boolean", // 更新设计画布后是否需要更新预览图
}

SDK 产品 APIs

获取产品信息

方法：

sdk.getProductData();

参数：无

返回值：

{
  "id": 28047,
  "blankDesignUrl": "空白设计图",
  "name": "产品名称",
  "sku": "NZ2201189",
  "texture": {
    "name": "材质名称"
  },
  "english_name": "英文名称：wo-piece Swimsuit",
  "img_url": "图片：http://s3.cn-north-1.amazonaws.com.cn/photo-center-prov/images/91rr3AHARTasVhdqqVyNm4TGH9ub5wHb8VhZiE45/d08230777b445fcc5a4c9a9c5df4dc7a.jpg",
  "product_details": {
    "id": 3918,
    "reminder": "温馨提示",
    "product_id": 28047,
    "production_process": "生产工艺",
    "material_description": "材质说明",
    "product_performance": "产品性能",
    "applicable_scenarios": "适用场景",
    "washing_instructions": "洗涤说明",
    "special_description": "特别说明",
    "design_explanation": "设计说明",
    "design_area": "设计区域",
    "picture_request": "图片要求"
  }
}

获取产品的全部变体信息

方法：

sdk.getVariants();

参数：无

返回值：

[
  {
    "id": 28048, // 变体 ID，即 variantId
    "color":{
      "colorSort": 2,
      "color": "颜色块如：#ffffff",
      "opacity": "透明度如100",
      "color_name": "颜色名称"
    },
    "name": "尺寸",
    "sort": "顺序",
    "status": 1,
    "sku": "NZ2201189001",
    "unit_price": "单价",
    "size": "尺寸",
    "selected": true // 是否为当前选中的变体
  }
]

切换变体（根据变体ID）

方法：

sdk.switchVariantById(variantId, callback);

参数：

• variantId【number】：变体ID

• callback【function】：切换回调(reason) => { console.log(reason); }

  • reason.status 回调状态，success 切换成功，error 切换失败

返回值：无

获取当前变体的全部设计面信息

方法：

sdk.getDesignFaces();

参数：无

返回值：

[
  {
    "id":10051360, // 设计面 ID，即 layerId
    "name":"素材",
    "height": 1200,
    "width": 925,
    "thumbnail": "http://s3.cn-north-1.amazonaws.com.cn/photo-center-prov/images/91rr3AHARTasVhdqqVyNm4TGH9ub5wHb8VhZiE45/f8c21007e21ea13b8d23362c359d384e.jpg",
    "printHeight": 3000,
    "printWidth": 2313,
    "maskUrl": "http://s3.cn-north-1.amazonaws.com.cn/photo-center-prov/images/91rr3AHARTasVhdqqVyNm4TGH9ub5wHb8VhZiE45/53129e42e3f8d68b00067a0944e61fee.png",
    "selected": true // 是否为当前选中的设计面
  }
]

切换设计面（根据设计面ID）

方法：

sdk.switchDesignFaceById(layerId);

参数：

• layerId【number】：设计面ID

返回值：无

清空所有设计

方法：

sdk.clearAll(callback);

参数：

• callback【function】：操作回调(reason) => { console.log(reason); }

  • reason.status 回调状态，success 清除成功，error 清除失败

返回值：无

备注：该方法是清除所有设计面的设计内容

将当前设计面的设计内容复制到其他面（根据设计面ID）

方法：

sdk.copyDesignByLayerId(layerId, callback);

参数：

• layerId【number】：设计面ID，传 -1 则表示复制到全部的设计面

• callback【function】：操作回调(reason) => { console.log(reason); }

  • reason.status 回调状态，success 设置成功，error 设置失败

返回值：无

保存设计

方法：

sdk.saveDesign(callback, customParam = null);

参数：

• callback【function】：操作回调(reason) => { console.log(reason); }

  • reason.status 回调状态，success 保存成功，error 保存失败

  • reason.data 回调数据，返回成品id与设计记录task_id（如果syncMode为async，则只返回设计记录task_id）

  • reason.customParam 自定义参数

• customParam【object】：自定义参数，会随回调函数一起返回，选填

返回值：无

备注：设计时对应的产品要加入到产品库，否则会报错合成id不能为空

SDK 设计画布 APIs

设置画布背景色

方法：

sdk.sarto.setBackground(color);

参数：

• color【string】：色值，接受 hex 或 rgb(a) 或 hsl 格式

返回值：无

获取画布背景色

方法：

const color = sdk.sarto.getBackground();

参数：无

返回值：

• color【string】：色值，接受 hex 或 rgb(a) 或 hsl 格式

清空画布设计

方法：

sdk.sarto.clear();

参数：无

返回值：无

备注：该方法是清除当前设计面的设计内容

添加文本图层

方法：

sdk.sarto.addText();

参数：无

返回值：无

备注：新添加的文本图层，其默认文本内容为：”Double Click Editing”，当用户双击对应的文本图层即可使用模态框对内容进行编辑。

对选中的文本图层设置字体

方法：

sdk.sarto.updateSDKFontFamily(fontFamily, callback);

参数：

• fontFamily【string】：字体，初始字体为 “Arial”

• callback【function】：操作回调(reason) => { console.log(reason); }

  • reason.status 回调状态，success 设置成功，error 设置失败

返回值：无

备注：

• 支持的字体可以参考本文档中《CSS 字体预声明》中CSS文件内列出的字体

• 设置字体时，因为 SDK 需要按需加载远程的字体，所以本操作是异步执行的

对选中的文本图层设置字号

方法：

sdk.sarto.updateFontSize(fontSize);

参数：

• fontSize【number】：字号

返回值：无

对选中的文本图层设置文字颜色

方法：

sdk.sarto.updateFontColor(color);

参数：

• color【string】：色值，接受 hex 或 rgb(a) 或 hsl 格式

返回值：无

对选中的文本图层设置内容对齐方式

方法：

sdk.sarto.updateTextAlign(type);

参数：

• type【string】：对齐方式

  • left 左对齐

  • center 居中对齐

  • right 右对齐

返回值：无

添加图片图层

方法：

sdk.sarto.addSDKImage(file, callback);

参数：

• file【File】：图片的 input[file] 元素

• callback【function】：操作回调(reason) => { console.log(reason); }

  • reason.status 回调状态，success 添加成功，error 添加失败

  • reason.data 回调数据，如图片信息等

返回值：无

备注：添加图片图层的时候，图片需要上传至我们的图片服务器，并且生成设计时使用的缩略图

添加素材图片（根据素材ID）

方法：

sdk.addMaterialById(id, callback);

参数：

• id【number】：素材id

• callback【function】：操作回调(reason) => { console.log(reason); }

  • reason.status 回调状态，success 添加成功，error 添加失败

  • reason.data 回调数据，如图片信息等

返回值：无

备注：特殊方法，不挂在 sdk.sarto 下，一般情况下不推荐使用

对选中的图片图层设置适应类型

方法：

sdk.sarto.updateImageLimit(type);

参数：

• type【string】：适应类型

  • fill 填充

  • fit 适应

  • extrude 拉伸

返回值：无

对选中的图片图层设置平铺

方法：

sdk.sarto.tiling(isForce, type);

参数：

• isForce【boolean】：是否无视当前选中图层的状态而设为平铺，一般设为 true 即可

• type【string】：平铺类型

  • basic 基础平铺

  • half-brick 横向交错平铺

  • half-drop 纵向交错平铺

  • mirror 镜像平铺

  • random 随机平铺

返回值：无

对选中的图片图层取消平铺

方法：

sdk.sarto.clearGroup();

参数：无

返回值：无

复制选中的图层

方法：

sdk.sarto.copy();

参数：无

返回值：无

删除选中的图层

方法：

sdk.sarto.delete();

参数：无

返回值：无

上升选中的图层（指图层顺序）

方法：

sdk.sarto.up();

参数：无

返回值：无

下沉选中的图层（指图层顺序）

方法：

sdk.sarto.down();

参数：无

返回值：无

置顶选中的图层（指图层顺序）

方法：

sdk.sarto.top();

参数：无

返回值：无

置底选中的图层（指图层顺序）

方法：

sdk.sarto.bottom();

参数：无

返回值：无

向左对齐选中的图层（相对于可设计区域）

方法：

sdk.sarto.alignLeft();

参数：无

返回值：无

向右对齐选中的图层（相对于可设计区域）

方法：

sdk.sarto.alignRight();

参数：无

返回值：无

水平对齐选中的图层（相对于可设计区域）

方法：

sdk.sarto.horizontal();

参数：无

返回值：无

垂直对齐选中的图层（相对于可设计区域）

方法：

sdk.sarto.verticle();

参数：无

返回值：无

向上对齐选中的图层（相对于可设计区域）

方法：

sdk.sarto.alignTop();

参数：无

返回值：无

向下对齐选中的图层（相对于可设计区域）

方法：

sdk.sarto.alignBottom();

参数：无

返回值：无

缩放选中的图层

方法：

sdk.sarto.zoom(type);

参数：

• type【string】：缩放类型

  • in 放大至 1.1 倍

  • out 缩小至 0.9 倍

返回值：无

旋转选中的图层

方法：

sdk.sarto.updateCommonAngle(type);

参数：

• type【string】：旋转类型

  • counterclockwise 逆时针旋转 45°

  • clockwise 顺时针旋转 45°

返回值：无

翻转选中的图层

方法：

sdk.sarto.updateCommonFlip(type);

参数：

• type【string】：翻转类型

  • x 沿 x 轴翻转

  • y 沿 y 轴翻转

返回值：无

设置选中图层的透明度

方法：

sdk.sarto.setOpacity(value);

参数：

• value【number】：透明度值，取值范围 0 ~ 1

返回值：无

隐藏图层（根据画布图层顺序下标）

方法：

sdk.sarto.hideByIndex(index);

参数：

• index【number】：对应图层在图层顺序中的下标

返回值：无

显示图层（根据画布图层顺序下标）

方法：

sdk.sarto.showByIndex(value);

参数：

• index【number】：对应图层在图层顺序中的下标

返回值：无

撤销画布操作（指画布设计操作记录）

方法：

sdk.sarto.undo();

参数：无

返回值：无

恢复画布操作（指画布设计操作记录）

方法：

sdk.sarto.redo();

参数：无

返回值：无

SDK 卸载

为了减少对浏览器内存的占用，在你的前端应用中，有一些场景（例如 React 的 componentWillUnmount、Vue 的 beforeDestroy、Angular 的 OnDestroy 等生命周期中），我们可以主动去卸载和销毁 SDK 的实例，这个时候可以调用以下方法：

sdk.remove();

参数：无

返回值：无

Demo

• 演示页