插件 embedly jquery 中文API文档
插件 embedly jquery 中文API文档
- Github 地址：https://github.com/embedly/embedly-jquery
- 源码下载： -
- 效果演示： -
嵌入式jQuery
Embedly jQuery是一个用于与Embedly API交互的jQuery库。
基本设置
嵌入式jQuery需要jQuery 1.5或更高版本，因为它使用延迟对象。将jQuery和Embedly jQuery添加到您的文档中。
<head>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.2/jquery.min.js" type="text/javascript"></script>
<script src="http://cdn.embed.ly/jquery.embedly-3.1.2.min.js" type="text/javascript"></script>
</head>
您现在可以使用jQuery选择器替换嵌入内容的链接：
$('#content a').embedly({key: 'Your Embedly Key'});
或者现在可以直接使用客户端：
$.embedly.extract('http://embed.ly', {key: 'Your Embedly Key'}).progress(function(data){
alert(data.title);
});
Key
嵌入式要求您在每次请求时传递密钥。要注册密钥，请访问app.embed.ly/signup。为避免将密钥添加到每个$.embedly调用中，您可以将其添加到defaults类似内容中，以便：
$.embedly.defaults.key = 'Your Embedly Key';
# Directly
$.embedly.extract('http://embed.ly').progress(function(data){alert(data.title)});
# CSS Selector
$('a').embedly();
否则你必须将它添加到每个请求，如下所示：
# Directly
$.embedly.extract('http://embed.ly', {key:'Your Embedly Key'})
.progress(function(data){alert(data.title)});
# CSS Selector
$('a').embedly({key:'Your Embedly Key'});
对于文档的其余部分，我们将假设您设置默认值或key直接传递给调用。
选择
使用CSS选择器将每个有效链接替换为页面上的嵌入。
$('a').embedly( options );
# Replace all valid links
$('a').embedly();
# Replace a subset of links
$('a.oembed').embedly();
# Replace with maxWidth option set to 600px and method option set
# to 'after'
$('a').embedly({query: {maxwidth: 600}, 'method':'after'});
# Replace only Hulu links
$('a').embedly({
query: {maxwidth: 600},
urlRe: /http:\/\/(www\.hulu\.com\/watch.*)/i,
method:'after'
});
# Embedly supports chaining, so you can modify your original jQuery set
# after triggering Embedly
$('a').embedly().css('backgroundColor','#dadada');
客户
选择器非常适合将嵌入数据插入DOM，但如果您希望更好地控制使用嵌入数据的方式，请直接使用客户端。
客户端遵循jQuery的Promise模式。您应该熟悉延迟对象的概念。在使用客户端之前，我们将在这里用一个简单的例子来解释。
var deferred = $.embedly.extract(['http://embed.ly', 'http://google.com'], {
key: 'xxxxxx',
query: {
words: 20,
}
}).progress(function(data){
// Called after each URL has been returned from the Embedly server. Order
// is not preserved for this method, so for long lists where URLs need to
// be batched the data results will likely be out of order.
console.log(data.url, data.title);
}).done(function(results){
// Called after the call has been completed with every data result in a
// list. Order is preserved in this method regardless of batching.
$.each(results, function(i, data){
console.log(data.original_url)
});
});
// Deferred objs retain information, so you can register callbacks even after
// the ajax call was completed.
deferred.done(function(results){
// This will execute immediately if the ajax call is complete
console.log('done', results.length);
});
deferred.progress(function(data){
// If the call has been completed, the deferred object will only pass back
// the last object that was sent to the notify function. You should
// register a progress function immediately after the embedly client call
// to catch all notify events.
alert('last object', data.url);
});
您也可以将单个URL传递给客户端，但该done方法将始终传递结果列表。
$.embedly.oembed('http://embed.ly').progress(function(data){
// Will only be called once in this case.
console.log(data.url, data.title);
}).done(function(results){
// Even though there was only one url, this will still be a list of
// results.
var data = results[0];
});
客户端也支持链接：
$.embedly.oembed(['http://embed.ly', 'http://apple.com'])
.then(function(data){
// Return only the titles. return data.map(function(d){return d.title;});
}).then(function(titles){
// yay titles console.log(titles)
});
方法
客户端只有4种方法
oembed
对应于Embedly的oEmbed API端点。可与Embed产品一起使用。
extract
对应于Embedly的Extract API Endpoint。适用于Extract产品。
preview
对应于Embedly的预览 API端点。适用于旧版计划。
objectify
对应于Embedly的Objectify API Endpoint。适用于旧版计划。
配料
Embedly的API每个API请求最多只接受20个URL，因此该ajax方法会自动将URL批量分组为20个。progress当URL的数据准备好并且该done方法将保留顺序时，该 方法仍将返回 。如果您想要较小的批量大小，可以batch在选项中指定，如下所示：
$.embedly.oembed(['http://embed.ly', ....], {batch:10}).done(function(results){
console.log(results.length);
});
数据
客户端传回的数据是Embedly API返回的数据的JSON对象。有关响应的更多信息，请参阅响应文档。
唯一的区别是oEmbed数据对象包含original_url用于簿记目的的 属性。
选项
key [ string:’’]
您可以以现有用户身份注册或登录，以检索您的Embedly密钥。密钥将允许更高的使用级别和额外功能，请参阅产品。
query [ Object:default object]
直接传递给Embedly API接受的所有Query Arguments。这些将与key，endpoint以及urls形成对Embedly的请求：
query: {
maxwidth: 400,
maxheight: 400,
chars: 200,
autoplay: true
...
}
有关更多信息，请阅读Query Arguments文档。
display [ 功能：默认功能]
此方法将内容嵌入页面。为方便起见，如果您使用oembed端点，Embedly内置了一个简单的显示功能。它将为photo类型创建一个图像，为类型嵌入一个简单的标题和描述，link并直接嵌入html for rich和 videotypes。
通常，您需要覆盖此功能以获得更加个性化的外观。
display 应该接受一个数据对象：
$('a').embedly({display:function(data){
$(this).text(data.title);
});
method [字符串： ‘替换’]
一个字符串值，用于告知Embedly在使用默认显示功能时如何将内容放入页面中。
- replace - 用内容替换链接
- after - 在链接后插入内容
- afterParent - 在父元素之后插入内容
- replaceParent - 用embed内容替换parent元素
wrapElement [字符串： ‘DIV’]
一个字符串值，表示用于包装内容的有效HTML元素。
className [字符串： ‘嵌入’]
一个字符串值，表示要分配给wrapElement的CSS类。
addImageStyles [ 布尔值：真]
一个布尔值，表示Embedly是否应使用样式元素根据maxWidth和maxHeight参数调整图像大小。
endpoint [ 字符串：透过oEmbed]
映射到Embedly端点的字符串值。预览和Objectify端点仅适用于 旧版计划。
- oembed - 第三方嵌入中的标准，包含一组有限的属性。
- 提取 - 返回各种属性（文章文本，图像，主色，关键字，相关链接和页面中的嵌入），以创建链接体验。
- 预览 - 返回一组更大的属性（多个图像，RSS内容和页面中的嵌入），用于自定义嵌入。
- objectify - 返回Embedly为链接提供的所有元数据和API数据。高级用户。
打算使用Extract，Preview或Objectify的开发人员必须包含他们自己的display回调函数来处理嵌入。我们的默认display回调仅适用于oembed。
urlRe [ 正则表达式：]
表示显示内容的链接的正则表达式。使用我们的 生成器为特定的源集生成正则表达式。
secure [ 布尔值：空]
默认情况下，嵌入式jQuery将用于window.location.protocol确定您的请求是否需要发送到HTTPS端点或HTTP。您可以通过将secure参数显式设置为truefor https或falsefor HTTP 来覆盖它。
batch [ 整数：20]
Embedly的API每个请求最多只接受20个URL，因此客户端将这些URL批量分组为20个。如果要设置自定义大小，可以使用此参数进行批量处理。
progress [ 功能：空]
直接添加到Deferred对象，并在API返回此URL的JSON数据时调用。progress应接受单个数据对象，并且不包含有关正在操作的元素的任何信息。
$('a').embedly({progress:function(data){
console.log(data.type)
});
done [ 功能：空]
直接添加到Deferred对象，并在Embedly API处理每个URL时调用。done应该接受数据对象列表。
$('a').embedly({done:function(data){
console.log(data.type)
});
错误和无效的网址
用户生成的内容很可能会将大量无效的URL传递给客户端。如果您还使用特定的URLRe，则会收到更多无效的网址。对待这些的客户端和选择来了，他们仍然传递给progress，done和 display功能。处理这些很容易：
$.embedly.objectify('notaurl').progress(function(data){
if (data.invalid === true){
// The URL that you passed in was not a good one.
console.log(data.error, data.error_message);
} else if (data.type === 'error'){
// The API passed back an error.
console.log(data.type, data.error_message);
} else {
// Everything is good to go. Proceed Captain.
}
})
数据/自定义事件
从版本2.0.0开始，我们已经开始使用jQuery.data（）将嵌入数据写入DOM元素。您可以在此处阅读有关数据函数的更多信息，但基本上将Embedly数据保存在元素上以便以后检索。例如：
# $('a').embedly()
# ... after the AJAX returns an oembed ...
$('a').data('embedly')
此调用返回embedly每个标记的对象，因此您可以稍后访问该数据。因为在AJAX请求完成之前，这些数据不会写入DOM，所以displayed.当使用jQuery.data（）将oEmbed对象写入节点时，我们为每个节点添加了一个名为This event 的自定义事件监听器 。我们这样做是为了让开发人员可以继续使用我们的默认回调函数将嵌入编写到页面中，并且仍然可以访问embedly数据以进行自定义。
# version 1
$('a').embedly().bind('displayed', function(e){
var data = $(this).data('embedly');
alert(data.title);
});
# version 2
$('a').embedly().bind('displayed', function(e, data){
alert(data.title);
});
如果你不想使用jQuery.data（），事件处理程序也会获取作为参数传入的embedly对象; 两者是等价的。
使用embedly数据可以让自己陷入竞争状态，其中使用启动事件并且数据尚未返回。为了解决这个loaded问题，数据上有一个Deferred Object，它将在一切就绪后解析。这是一个简单的例子：
$('a').embedly().on('click', function(){
var embed = $(this).data('embedly');
// Attach a done event to the loaded object that will be called when
// everything is ready.
embed.loaded.done(function(data){
alert(data.url);
});
});
图像代理和调整大小
通过嵌入显示 ，您可以访问图像代理并调整端点大小，从而可以将图像缩放到任意大小。
您可以使用$ .embedly.defaults来设置键或查询调整大小参数：
$.embedly.defaults.key = 'Your Embedly Key';
$.embedly.defaults.query = {width: 300};
您可以使用选择器来调整图像大小或代理图像，我们将使用data-src属性查找所有图像：
e.g. <img data-src="http://embed.ly/static/images/logos/logo_color.png"></img>
$('img').display('resize', {query: {width: 300}});
或者使用客户端生成图片网址：
$.embedly.display.resize('http://embed.ly/static/images/logos/logo_color.png', {query: {width: 300}});
图像方法
图像显示客户端有4种方法，每种方法有2个参数：url，options。每个方法都返回一个可以添加到DOM的图像URL。
display
对应于Embedly的Display API端点，用于简单地代理图像。通过HTTPS为代理添加安全性。
resize
对应于Embedly的Resize API Endpoint，用于通过将图像缩放到保留纵横比的特定宽度或高度来调整图像大小。必需的查询参数：宽度或高度。可选：成长。
crop
对应于Embedly的Crop API端点，用于将图像裁剪为特定的宽度和高度。必需的查询参数：宽度，高度。
fill
对应于Embedly的填充 API端点，用于将图像适合填充特定颜色的特定画布大小。必需的查询参数：宽度，高度，颜色。
显示方法参数
endpoint [字符串： ‘显示器’] 图像方法：显示，调整大小，裁剪或填充。（需要） options [对象：默认对象] 直接传递给Embedly Display端点接受的所有Query Arguments。这些将与Embedly 结合key并 url形成请求。请参阅下面的查询部分 参数：
options: {
key: 'your Embedly key',
query: {
width: 400,
height: 400,
color: #fff,
...
}
}
必需的查询参数因端点而异，您可以参考Display端点文档。
图像查询参数
这些是可以通过选项传递的查询参数。这些参数应该添加到options.query中：
width [ 整数：空]
您想要缩放图像的宽度。
height [ 整数：空]
您想要缩放图像的高度。
color [ 字符串：空]
用3或6个十六进制字符填充图像的颜色。（fff，4f2a55）
grow [ 布尔值：假]
默认情况下，API不会增加图像的大小。设置为true允许图像增大。
errorurl [ 字符串：空]
如果原始图像无效或无法处理，将使用的后退图像URL。确保此图像存在。
CDN
为了让您更快，Embedly在cdn.embed.ly上托管您需要的所有文件。也可通过HTTPS获得。最新版本可在此处获得：
http://cdn.embed.ly/jquery.embedly-3.1.2.js
http://cdn.embed.ly/jquery.embedly-3.1.2.min.js
