欢迎使用Picself API

使用picself API可以将picself嵌入到您的网页中,等用户编辑完图片后,保存回您的网站。

Picself在线图片编辑器简单易用但功能强大,丰富的字体、图案、边框以及专业摄影特效可以使您的照片获得绝妙的效果。现在我们已经和新浪博客、新浪微博、开心网等网站建立合作关系,给用户带去更加丰富的体验,如果您的网站想将Picself作为图片处理工具,欢迎您的加入。

Picself对外完全开放,我们提供各种接口,简单易用,可以方便网站用户轻松制定适合自己的版本,如果您有任何疑问或建议,请发送到picself#vip.sina.com(用@替换#)。

开始之前

你首先需要申请App Key

 

说明:如果你是SAE(http://sae.sina.com.cn/)用户,可以不用申请app key,使用SAE的key即可。但是在调用picself接口的时候,需要加上ClientFrom参数(ClientFrom=sae)。

 

如何申请?

请发邮件到picself#vip.sina.com(用@替换#),邮件格式如下;

标题:申请 App key-公司名称

正文:

公司名称:XXXXX

联系方式:xxx@xxx.com, 135XXXXXXX

访问域名:如:kaixin001.com

为什么要申请?

在拥有了App key之后,您不仅可以在贵网站中使用Picself,而且我们将提供给您详细的用户统计信息,并且还可以开展深度合作。

演示

浮层的示例,点击这里查看。

嵌入网站的示例,点击这里查看。

将图片引入Picself主页,编辑后返回的示例,点击这里查看。

开发手册

说明

Picself API,可以使用Javascript或者URL两种方式调用,这两种方式可以实现不同的调用效果。下面的例子点击可以查看,打开后右键可以查看源码。

1 浮层方式

1.1 如何调用picself

1、设置crossdomain.xml

在crossdomain.xml里添加如下的语句:

<allow-access-from domain="picself.cn"/>

<allow-access-from domain="*.picself.cn"/>

例如贵公司保存图片的服务器地址为: http://xxx.com.cn,那么crossdomain.xml的路径为 http://xxx.com.cn/crossdomain.xml。如果您不知道如何使用此文件,也可以下载http://www.picself.cn/crossdomain.xml到您根目录下,做相应修改即可。

2、引用JS代码

在你的网页代码的head标签里或者body标签里加入代码。

<script src="http://www.picself.cn/service/picself.js" type="text/javascript"></script>

3、初始化picself

在你的网页代码的body标签里加入picself的构造函数:

var ps =new Picself(width,height, wmode, returnArgs, clickObject);

这句JS的作用是,为clickObject(如一个按钮),增加一个点击响应,点击clickObject则弹出一个width*height的浮动窗口,当操作完毕时,调用函数returnArgs。

下面介绍一下Picself对象构造函数的参数及其意义

参数意义
width Picself对象的显示宽度,当为100%时,那么将100%显示
height Picself对象的显示高度,当为100%时,那么将100%显示
wmode Picself的显示模式,为"Window"时加载速度最快,"Transparent"时显示效果好。建议值为: "Transparent"
returnArgs 保存完图片,贵公司希望自己来控制跳转,那么保存完图片,将调用该名称的函数。(在后面将介绍此函数的用法)
clickObject 表示该对象将监听clickObject对象的点击事件,当点击后,出现一个picself浮层对象

下面是一个简单的例子

例1浮层显示picself(打开网页后,右键查看源文件)

注意:此时的保存按钮不可用,右上角的关闭按钮也不能使用,后面将对其添加相应相应。

1.2参数设置

例1浮层显示picself 给按钮添加了弹出Picself浮层的响应,下面将介绍如何设置picself浮动窗口的属性,使其适应您的应用。

设置方法:

ps.initArgs(argsName,argsValue);

argsName的意义请见表1 Picself的参数及意义

下面介绍两个常用的属性:

ClientName:调用Picself的名称,即AppKey值。例子:ps.initArgs("ClientName","1001016");

PicUrl: 要编辑的图片URL地址,如果没有,不需要设置. 例子:

ps.initArgs("PicUrl","http://service.photo.sina.com.cn/middle/50b42af1t8d16778e6e4e&690")

例2 用picself浮层打开网络图片

表1 Picself的参数及意义中还有其他参数,我们将在下面进行介绍。

1.3 保存图片

当图片编辑完毕,我们将用POST方式,将图片提交给您想要接收图片的页面。下面介绍几个与图片保存相关的属性。

  • UploadType: 保存模块下,是否要显示只保存的地址,要允许显示保存本地等,默认是全部显示。默认值为:all 即允许保存到所有站点;当为: common时,那么只能保存到贵站点的站点;当为nocommon时,将不能保存到贵网站,只能保存到默认的站点。 例子:ps.initArgs("UploadType","common");
  • ImageFileName: 保存时,上传图片文件的名称,当选择保存时,此项为post的文件名。例子:ps.initArgs("ImageFileName","pic");
  • UploadUrl: 保存时,接收图片的网址(POST方式)。例子:ps.initArgs("UploadUrl","http://www.xxx.com/uploadPic.php");
  • UploadName:当UploadType为all时,保存按钮显示的名字。若UploadType为common或者nocommon时,不显示。例子:ps.initArgs("UploadName","保存到开心网");

1、设置UploadUrl

要将编辑好的图片传到您的网站,您需要准备这样一个接收图片的UploadUrl,我们将编辑好的图片用post的方法传到您的网页,您可以对其进行操作。

注意:如果想接收较大的图片,需要将apache或者IIS的上传文件配置改到较大的数值,如10M。

例如:ps.initArgs("UploadUrl","http://www.xxxx.cn/uploadPic.php");

例如这样的一个uploadPic.php的代码:

<?php

function random($len){

  $srcstr="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";

  mt_srand();

  $strs="";

  for($i=0;$i<$len;$i++){

    $strs.=$srcstr[mt_rand(0,35)];

  }

  return strtoupper($strs);

}

$name = random(32).".jpg";

if($_FILES['pic']['error']==UPLOAD_ERR_OK){

  move_uploaded_file($_FILES['pic']['tmp_name'],$name);

echo '{

  "code":"A00008","message":"success","data":"http://localhost/sample/up/'.$name.'"}';

}else{

  echo '{"code":"-A00001","message":"fail","data":"http://localhost/sample/up/'.$name.'"}';v
}

?>

把此php页面作为接收UploadUrl,当其接收到图片时,就会给图片命名并保存起来,然后返回保存结果。

UploadUrl有两个作用:

(1)处理上传图片。

(2)为picself返回处理结果

返回处理结果的格式如下:

{"code":"A00008","message":"success","data":"http://www.xxx.com/picname.jpg"}

code:结果处理方式,参见表2 保存返回值

Message:返回的消息(如保存失败时,会在picself中显示此消息)

Data:当code码为A00006时,data内容为程序要跳转的URL地址。当code为A00008时,data可以存储用户想要的数据。

注意:此PHP必须保存成utf-8格式,否则返回的message可能出现中文乱码!

注意:此PHP必须保存成utf-8格式,否则返回的message可能出现中文乱码!

2、UploadUrl返回结果后的操作

当图片保存成功,返回码为A00006时,picself会自动跳转到data所指定的网址。 而当code为A00008时,picself不会跳转,而是会调用returnArgs函数(此函数在picself构造函数里指定的)。此时需要在你的网页JS代码中加入以下代码:

/**

  * 添加这个函数到到JS代码中,这个函数时在当Picself上传图片完成后调用

  *{"code":"A00008","message":"保存成功","returnUrl": "www.XXX.cn" }

  * @param key 为code值

  * @param data 为{"code":"A00008","message":"成功","returnUrl": "www.XXX.cn" }

**/

function returnArgs(key,data){

  if(key == "A00008"){//当key为A00008时,表示成功调用上传图片

    //data为returnUrl数值

    ps.close();//当您使用的时"clickObject"方式建立的此方法关闭浮动层。

  }else if( key == "Close"){

    ps.close();

  }

}

注意:不能在returnArgs函数里加入alert提示框,否则会造成火狐下picself不能正常使用!(关闭时,已经在picself内部弹出是否要关闭提示框)

其中:Key为返回的key值,当点击picself右上角的关闭按钮时,key值为"Close"。

例3 Picself浮层完整示例

1.4 JavaScript函数及其意义

/**

  * Picself对象构造函数

  * @param width Picself对象的显示宽度,当为100%时,那么将100%显示

  * @param height picself对象的显示高度,当为100%时,那么将100%显示

  * @param wmode Picself的显示模式,为"Window"时加载速度最快,"Transparent"时显示效果好。建议值为: "Transparent"

  * @param returnArgs Picself保存完图片,贵公司希望自己来控制跳转,那么保存完图片,将调用该名称的函数

  * @param clickObject 表示该对象将监听clickObject对象的点击事件,当点击后,出现一个picself对象,

  * 那么就不需要执行ps.setContainer("picselfDivContainer")

*/

function Picself(width,height,wmode,returnArgs,clickObject);

/**

  * 设置相应的参数

  * @param argsName 设置的参数名称

  * @param argsValue 参数值

*/

ps.initArgs(argsName,argsValue);

/**

  *当使用的时"clickObject"方式建立的此方法关闭浮动层,仅限于关闭浮层

*/

ps.close();

/**

  * 将Picself对象添加到指定的Div面板中

  * @param container 页面中要显示Picself对象的名称,数据类型为字符串

*/

ps.setContainer(container);

2 嵌入页面(Javascript)

如果想把picself嵌入到指定的div标签中,那么在构造函数时,就不需要指定对象,然后将其添加到相应的div标签即可,如:

var ps =new Picself(1000,600,"Window",null,null);

ps.setContainer(container);

其他的设置请参见1 浮层方式

例2-1 js嵌入页面

下面介绍的两种方法(与URL有关),如果贵网站的页面文件不是UTF-8编码,那么在传递中文参数的时候,需要将其URL Encoding才能正常传递,否则,将会是乱码。

3 嵌入页面(iframe)

3.1 如何调用picself

1、设置crossdomain.xml

找到贵公司的调用picself项目的相关域名下根目录的crossdomain.xml文件,在该文件中添加以下信息:

<allow-access-from domain="picself.cn"/>

<allow-access-from domain="*.picself.cn"/>

例如贵公司保存图片的服务器地址为: http://xxx.com.cn,那么crossdomain.xml的路径为 http://xxx.com.cn/crossdomain.xml。也可以下载http://www.picself.cn/crossdomain.xml到根目录下。

在body标签里添加如下代码:

<div>

  <iframe src="http://www.picself.cn/service/" frameborder=no scrolling=no width=1000 height=600>

  </iframe>

</div>

例3-1 iframe调用picself

3.2参数设置

这种方法里,使用URL何给picself传递参数,参数列表见表1 Picself的参数及意义。例如我们要传递ClientName和PicUrl,只需把URL写成

http://www.picself.cn/service/?ClientName=0000000&PicUrl=example.jpg

例3-2 URL参数传递

3.3保存图片

图片编辑完毕后,将用POST方式保存到指定的页面。下面介绍几个与图片保存相关的属性。

  • UploadType: 保存模块下,是否要显示只保存的地址,要允许显示保存本地等,默认是全部显示。默认值为:all 即允许保存到所有站点;当为common时,那么只能保存到贵站点的站点;当为nocommon时,将不能保存到贵网站,只能保存到默认的站点。例子:ps.initArgs("UploadType","common");
  • ImageFileName: 保存时,上传图片文件的名称,当选择保存时,此项为post的文件名。例子:ps.initArgs("ImageFileName","pic");
  • UploadUrl: 保存时,接收图片的网址(POST方式)。例子:ps.initArgs("UploadUrl","http://www.xxx.com/uploadPic.php");
  • UploadName:当UploadType为all时,保存按钮显示的名字。若UploadType为common或者nocommon时,不显示。例子:ps.initArgs("UploadName","保存到开心网");

1、设置UploadUrl

要将编辑好的图片传到您的网站,您需要准备这样一个接收图片的UploadUrl,我们将编辑好的图片用post的方法传到您的网页,您可以对其进行操作。

例如:http://www.picself.cn/service/?UploadUrl=http://www.xxx.com/uploadPic.php

例如如下uploadPic.php的代码:

<?php

function random($len){

  $srcstr="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";

  mt_srand();

  $strs="";

  for($i=0;$i<$len;$i++){

    $strs.=$srcstr[mt_rand(0,35)];

  }

  return strtoupper($strs);

}

$name = random(32).".jpg";

if($_FILES['pic']['error']==UPLOAD_ERR_OK){

  move_uploaded_file($_FILES['pic']['tmp_name'],$name);

  echo

  '{"code":"A00006","message":"success","data":"http://localhost/sample/up/'.$name.'"}';

}else{

  echo

  '{"code":"-A00001","message":"fail","data":"http://localhost/sample/up/'.$name.'"}';

}

?>

把此php页面作为接收UploadUrl,当其接收到图片时,就会给图片命名并保存起来。

UploadUrl有两个作用:

(1) 处理上传图片。

(2) 为picself返回处理结果。

返回处理结果的格式如下: {"code":"A00006","message":"success","data":"http://localhost/sample/up/'.$name.'"}

code:代表了不同的意义,参见表2保存返回值。 注意:在这种方式下,成功只能返回A00006,也就是说保存成功之后页面只能跳转。

Message:返回的消息(如保存失败时,会在picself中显示此消息)

Data:当code码为A00006时,data内容为程序要跳转的URL地址。当code为A00008时,data可以存储用户想要的数据。

2、UploadUrl返回结果后的操作。

当图片保存成功,返回码为A00006时,picself会自动跳转到data所指定的网址。 例如我们把URL设为:

http://www.picself.cn/service/?ClientName=1001016&PicUrl=http://tw.people.com.cn/mediafile/200903/09/F200903091433043242020611.jpg&UploadUrl=http://localhost/sample/up/uploadPic.php&ImageFileName=pic&UploadType=common

效果如例3-3 iframe调用Picself

4 导入Picself主站

使用用URL(具体的使用方法请参见3 嵌入页面iframe)的方法也可以直接跳到主站(www.picself.cn),编辑完后关闭或者跳转。

例4-1 跳转到Picself主页。(右键查看代码)

参考

表一:传入参数及其意义

参数 意义
ClientName 调用Picself的名称,即AppKey值。例子:ps.initArgs("ClientName","1001016");
ClientFrom 仅供sae用户使用,如果是sae用户,需要设置此属性。例子:ps.initArgs("ClientFrom","sae");
PicUrl 要编辑的图片URL地址,如果没有,不需要设置. 例子:
ps.initArgs("PicUrl","http://service.photo.sina.com.cn/middle/50b42af1t8d16778e6e4e&690");
UploadUrl 保存时,接收图片的网址(POST方式)。例子:
ps.initArgs("UploadUrl","http://www.xxx.com/uploadPic.php");
ImageFileName 保存时,上传图片文件的名称,当选择保存时,此项为post的文件名。默认为“pic”,例子:
ps.initArgs("ImageFileName","pic");
PicName 文件原名(不带扩展名,如mypic.jpg,可传入“mypic”),一般可不设置此参数,例子:
ps.initArgs("PicName","mypic");
UploadType 保存模块下,是否要显示只保存的地址,要允许显示保存本地等,默认是全部显示。默认值为:all 即允许保存到所有站点;当为: common时,那么只能保存到贵站点的站点;当为nocommon时,将不能保存到贵网站,只能保存到默认的站点。例子:
ps.initArgs("UploadType","common");
UploadName 当UploadType为all时,保存按钮显示的名字。若UploadType为common或者nocommon时,不显示。例子:
ps.initArgs("UploadName","保存到开心网");
CloseButton 是否在打开的Picself右上角显示关闭按钮,true时显示,false时不显示(在JS方式中默认为true,在URL方式中默认为flase,而且在URL方式中,不接受此参数,总是为false)。 例子:
ps.initArgs("CloseButton","false");
ScrollFlag 是否让Picself相应鼠标滚轮事件(防止与嵌入页面同时滚动),true时响应,false时不响应。例子:
ps.initArgs("ScrollFlag","true");
LockSaveParam 保存到第三方网站时,是否锁定保存页面的参数,true时不可以修改,false时可以修改。例子:
ps.initArgs("LockSaveParam","true");
UploadTip 这个用于表示鼠标经过第三方站点按钮的提示语 以及 小标题。默认为"保存图片"。(这个参数长度最好为7个中文字符或14个英文字符以内的长度。这样保障用户可以看到全部文字。但是如果传递长度超过此长度,并不会做截断。)例子:
ps.initArgs("UploadTip","保存到爱物网");
PicProxyFlag 这个表示我们picself去读取第三方的图片时,是否使用代理去抓取图片,默认值为true,如果对方允许我们picself域名直接访问其图片,那么就建议第三方这个值设置为false。(当为false时,需要调用方允许我们picself域名访问第三方的图片,而不认为是外链。)例子:
ps.initArgs("PicProxyFlag","false");

表二:返回值及其意义

参数 意义
A00006 表示成功,并跳转
A00008 表示成功,但是不做任何跳转,调用JS的returnArgs方法。(注:仅在浮动窗口时有用)
-A00001 表示存储出错
-A00002 表示参数错误
-A00003 表示用户存储空间不足
-A00004 表示用户没有权限

欢迎使用Picself API

演示

开发手册

1 浮层方式

1.1 如何调用picself

1.2 参数设置

1.3 保存图片

1.4 JavaScript函数及其意义

2 嵌入页面(Javascript)

3 嵌入页面(iframe)

3.1 如何调用picself

3.2 参数设置

3.3 保存图片

4 导入Picself主站

参考