ClippingMagic.js

ClippingMagic.js 允许您方便地将 Clipping Magic 编辑器集成到您自己的网站中去。 您可以像在标题页一样编辑单张图像,或者像在成批剪裁中一样编辑一系列图像。

请尝试

上载几张图像后,您能够在您的浏览器中运行以下范例,只需点击“尝试”按钮即可。

在普通 Clipping Magic 编辑器与 API 编辑器之间有一些很小的差别:

  • 帮助初始屏幕未显示。

易贴设置

如果您在呼叫ClippingMagic.edit()时传入useStickySettings=true,编辑器将使用其 API 键用于上载图像的用户当前配置的易贴设置。

这样您就可以对基本剪切设置进行一次配置,然后将其应用于您编辑的所有图像。

Read about how to configure the sticky settings

预剪裁在 API 中不可用,但您可以在 API 上载呼叫中配置图像尺寸限制。


设置

如需使用 ClippingMagic.js,首先在您希望允许编辑的页面包括和初始化该工具:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js" type="text/javascript"></script>
<script src="https://clippingmagic.com/api/v1/ClippingMagic.js" type="text/javascript"></script>
<script type="text/javascript">
  var errorsArray = ClippingMagic.initialize({apiId: 123});
  if (errorsArray.length > 0) alert("对不起,您的浏览器缺少一些要求的功能: \n\n " + errorsArray.join("\n "));
</script>

ClippingMagis.js 依赖 jQuery,因此请务必在载入 ClippingMagic.js 之前载入 jQuery。


编辑单张图像

您可以像这样显示编辑单张图像的编辑器:

ClippingMagic.edit({
    "image" : {
      "id" : 2345,
      "secret" : "image_secret"
    },
    "useStickySettings" : true,
    "locale" : "zh-Hans-CN"
  }, callback);

回拨功能将通过result-generatededitor-exit回拨,但不能二者同时使用。 二者均表示编辑器已关闭。

useStickySettings忽略或填充false以使用出厂默认设置。

请务必在文档就绪事件之后进行此次呼叫,因为它会引用 DOM。


编辑多张图像序列

您可以像这样显示编辑多张图像的编辑器:

ClippingMagic.edit({
    "images" : [ {
      "id" : 2345,
      "secret" : "image_secret"
    }, {
      "id" : 2346,
      "secret" : "image_secret2"
    } ],
    "useStickySettings" : true,
    "locale" : "zh-Hans-CN"
  }, callback);

回拨功能将通过result-generated为用户生成的每一个结果呼叫一次(= 每次点击‘完成’呼叫一次)。 结束时将有一次editor-exit通话,表示已经通过点击 X 或用完需要编辑的图像关闭编辑器。 当用户跳过一张图像时,没有回拨。

useStickySettings忽略或填充false以使用出厂默认设置。

请务必在文档就绪事件之后进行此次呼叫,因为它会引用 DOM。


回呼 function(opts)

edit功能将callback功能视为一个参数。 该回拨允许您对用户行动作出回应,并将图像编辑进展状况通知您的后端服务器。

回拨签名是function(opts)和任何例外情况,或返回数值被忽视。 opts参数是包含以下成分的 PlainObject

event

表示刚刚发生的状况的字符串,请参阅下表。

image 可选。 JSON 对象图像(仅包括 ID 和密钥)。
error 可选。 JSON 对象错误
事件有图像?有错误?表示
result-generated 用户已经点击‘完成’,已经生成结果,可使用后端 API 立即下载。 在单张图像模式,编辑器已关闭。
editor-exit 用户已经通过点击右上角的红色 X 或者用户在多张图像模式中用完需要编辑的图像,关闭编辑器。 编辑器已关闭。
error 出错。详情请检查error数值。 编辑器已关闭。

一旦编辑器关闭,您就可以再次呼叫edit()(此前的呼叫会导致异常)。

回拨调用范例

callback({
  "event" : "result-generated",
  "image" : {
    "id" : 2345,
    "secret" : "image_secret"
  }
}); 

功能定义

ClippingMagic.initialize(opts) -> array_of_missing_features

initialize功能需要包含配置初始化的键/数值对的 PlainObject

apiId
必须填写: 您的API ID。

该函数返回一个带字符串的 JavaScript 阵列,描述在当前浏览器中缺失的功能,但要求运行编辑器。 如果该阵列空置,您可以继续呼叫edit函数。

ClippingMagic.edit(opts, callback)

edit函数接受以下参数:

opts

必须填写: 包含配置初始化的键/数值对的PlainObject

image

可选。 JSON 对象图像(仅要求 ID 和密钥)。

images

可选。 JSON 对象图像阵列(仅要求 ID 和密钥)。

useStickySettings

可选。 Boolean, true意味着将使用 API 用户的易贴设置,false或缺少意味着将使用出厂默认值。

阅读关于在 API 中使用易贴设置的更多内容

locale

可选。 编辑器使用的显示语言。如果缺失,默认值为英文。有效值为:

代码显示语言
en-US English (英语)
de-DE Deutsch (德语)
es-ES Español (西班牙语)
fr-FR Français (法语)
it-IT Italiano (意大利语)
ja-JP 日本語 (日语)
ko-KR 한국어 (韩语)
pt-BR Português (葡萄牙语)
zh-Hans-CN 简体中文 (中文)
callback

必须填写: 详情请查看以上“回拨”一节。

这种方法不会返回数值。 如果在呼叫这种方法之前尚未呼叫initialize,或者如果initialize返回一个非空置阵列,或者如果编辑器窗口已经打开,则会引发异常。