Silverlight:Downloader对象详解

这篇是翻译Msdn2上面关于Silverlight的Downloader对象的文章，包括他的属性，方法，事件和Downloading Content on Demand这篇文章！我想很多人都看过这篇文章，但这次我将Downloader对象的所有方法和属性，事件都翻译过来也算是自己的学习笔记吧！大家一起共享！（除DependencyObject外的所有属性，方法，事件外）
在Silverlight.cn上有翻译QUICKSTART1.1中关于Downloader对象的文章。 http://myspace.silverlight.cn/QUICKSTART1.1_CH/Other/Download.aspx，是一个成功的案例，可以用来实践。
接下来还有很多的关于Silverlight的翻译。今天就到这里！

原文地址
请多指正：
下面的内容可以先参考：
Silverlight:Downloader的使用(Method篇)
二 Downloader的使用(属性)
Silverlight:Downloader的使用(event篇)
Silverlight:CreateFromXAMLDownloader

---

Downloading Content on Demand

---

Microsoft Silverlight提供一个Downloader对象,用来为a Silverlight plug-in.提供下载功能集合.

---

(1)Role Of Downloader Object

---

Downloader Object是专门为Silverlight 对象提供下载应用程序数据,如XAML, JavaScript,media,images,Downloader object 能提供一经应用程序响应就立即下载内容的功能,而不是当Silverlight plug-in初始化后就提供所有应用程序内容.更重要的是,你能呈现内容不需要刷新页面.Downloader object提供初始化数据传输,监控数据传输进程和找回下载内容等功能.你还能使用Downloader在后台预载内容能在有些场景中初始化更快如内容可能请求用户通过激活UI界面(如用户选择播放不同的media文件).

Downloader对象的属性和方法是模拟 XMLHttpRequest (XHR) 的APIs,XHR提供JavaScript和其他Web浏览器脚本语言传输从Web server端Http来的XML数据.并且操作数据.

---

(1)Download Packages

---

 Silverlight提供能将内容打包下载,是一个中立的文件集合包括XAML,media,和其他应用程序数据..zip文件格式被用来支持下载包.下面是详细的一个应用程序内容集合包括一个.zip下载包.

当包被成功的下载,你就能使用GetResponseText, SetSource (Image), SetSource (MediaElement), and CreateFromXAMLDownloader 等方法去找回包的详细part名.在这个case 中,在包内单个的文件名的参考为"otation01_green.png".

重新得到包中的part.

---

(2)Creating and Initailizing a Downloader Object

---

创建一个Downloader对象,使用Silverlight plug-in的CreateObject方法并保留一个返回对象引用.直到Silverlight plug-in已经完全初始化后才能调用CreateObject方法.
下面是JavaScript调用CreateObject方法创建一个Downloader对象.

//  Event handler for initializing and executing a download request.
function  onMouseLeftButtonUp(sender, eventArgs)
{
    // Retrieve a reference to the plug-in.
    var slPlugin = sender.getHost();

    // Create a Downloader object.
    var downloader = slPlugin.createObject("downloader");
}

因为Downloader操作是异步的,大部分与Downloader的交互操作将通过Event来完成,特别是要调用定义两个Downloader事件函数,DownloadProgressChanged和 Completed.并DownloadProgressChanged事件,允许你监控下载进程,边响应事件同时提供视觉反馈.

Completed事件允许你测定下载状态.
下面JavaScript事例显示怎样在Downloader object中.添加DownloadProgressChanged and Completed events .

//  Event handler for initializing and executing a download request.
function  onMouseLeftButtonUp(sender, eventArgs)
{
    // Retrieve a reference to the plug-in.
    var slPlugin = sender.getHost();

    // Create a Downloader object.
    var downloader = slPlugin.createObject("downloader");

    // Add DownloadProgressChanged and Completed events.
    downloader.addEventListener("downloadProgressChanged", onDownloadProgressChanged);
    downloader.addEventListener("completed", onCompleted);
}

接下来是调用Open方法初始化下载请求,并执行它,Open方法初始化Downloader对象并指定激活执行和被激活所执行的内容(指定action和content).下面是JavaScript怎样完整的的reate, initialize, and execute 一个下载请求.

//  Event handler for initializing and executing a download request.
function  onMouseLeftButtonUp(sender, eventArgs)
{
    // Retrieve a reference to the plug-in.
    var slPlugin = sender.getHost();

    // Create a Downloader object.
    var downloader = slPlugin.createObject("downloader");

    // Add DownloadProgressChanged and Completed events.
    downloader.addEventListener("downloadProgressChanged", onDownloadProgressChanged);
    downloader.addEventListener("completed", onCompleted);

    // Initialize the Downloader request.
    // NOTE: downloader APIs disallow file:\\ scheme
    // you must run this sample over localhost: or off a server or the following call will fail

    downloader.open("GET", "promo.png");

    // Execute the Downloader request.
    downloader.send();
}

---

(3)Defining Downloader Event Handlers

---

下面表格是Downloader object.提供的表格:

Event	Description
Completed (Downloader)	Occurs when the download request has completed and returned content.
DownloadFailed	Occurs when the download request has failed to return content.
DownloadProgressChanged (Downloader)	Occurs while content is being downloaded during a download request.

上面的内容可以在 Silverlight:Downloader的使用(event篇)中得到！

---

a:操作DownloadProgressChanged Event

---

DownloadProgressChanged 事件常常被用来显示进度视觉效果,显示下载的百分几.下面是制作一个进度条

< Canvas  Canvas.Top ="70" >
   < Rectangle
     x:Name ="progressRectangle"
    Canvas.Left ="20"
    Height ="10"  Width ="0"
    Fill ="Maroon"   />
   < Rectangle
     Canvas.Top  ="-1"
    Canvas.Left ="19"  Height ="12"
    Width ="202"
    StrokeThickness ="1"  Stroke ="Black"   />
   < TextBlock
     x:Name ="progressText"
    Canvas.Top  ="-4"  Canvas.Left ="230"
    Text ="0%"  FontSize ="12"   />
</ Canvas >

下面是定义DownloadProgressChanged事件操作函数.

//  Event handler for updating visual progress indicator
function  onDownloadProgressChanged(sender, eventArgs)
{
    // Calculate the downloaded percentage.
    var percentage = Math.floor(sender.downloadProgress * 100);

    // Update the Rectangle and TextBlock objects of the visual progress indicator.
    progressText.text = percentage + "%";
    progressRectangle.width = percentage * 2;
}

效果如下面的图:

一个进程视觉显示器能被构建是来于各种XAML,包括animated对象.进程是通过DownloadProgress属性报告的的,DownloadProgress属性是一个Double0,1之前的值.

---

b:Defining a Completed Event

---

当下载请求已经完成并返回内容时Completed 事件被触发.Completed事件一经调用,你能使用GetResponseText 方法或ResponseText属性去访问内容.
下面是JavaScript显示怎样定义一个Completed event.

//  Event handler for the Completed event.
function  onCompleted(sender, eventArgs)
{
    // Retrieve downloaded XAML content.
    var xamlFragment = sender.ResponseText;

    // Create the objects from the XAML content.
    var plugin = sender.getHost();
    var button = plugin.content.createFromXaml(xamlFragment);

    // Add downloaded XAML content to the root Canvas of the plug-in.
    var rootCanvas = sender.findName("rootCanvas");
    rootCanvas.children.add(button);
}

---

 C:Retrieving Downloaded Content

---

当Downloader对象求情完成时,来于ResponseText的属性值描述下载内容,这个值是字符串,响应文本横呈现一个个无格式的字符串, XMAL,JavaScript,media,image.

---

d:Using the URI Property to Identify Downloaded Content

---

当调用Send方法,你能指定一个URI参数来描述下载数据.URI属性允许你在多Downloader object下载时使用共同的DownloadProgressChanged or Completed event下载不同内容.(他能区分不同的Downloader object和事件).

下面JavaScript事例是显示在Completed 事件函数中使用URI属性激活GetResponseText方法.因为downloaded 内容不是以包的形式下载,所以GetResponseText方法的  part 参数必须为空字符串.

//  Event handler for the Completed event.
function  onCompleted(sender, eventArgs)
{
    if (sender.uri == "OK_button.js")
    {
        // Evaluate JavaScript code -- causes code to be memory-resident.
        eval(sender.ResponseText);
    }

    if (sender.uri == "OK_button.xaml")
    {
        // Retrieve downloaded XAML content.
        var xamlFragment = sender.ResponseText;

        // Create the objects from the XAML content.
        var plugin = sender.getHost();
        var button = plugin.content.createFromXaml(xamlFragment);

        // Add downloaded XAML content to the root Canvas of the plug-in.
        var rootCanvas = sender.findName("rootCanvas");
        rootCanvas.children.add(button);
    }
}

---

E:Retrieving Content from Packages

---

你的进程是单个物件下载返回的是字符串,Downloader还能返回包,是以.zip文件格式的包,在从.zip文件找和回内容,你要Completed event写一个操作者.你要使用GetResponseText方法而不使用ResponseText属性找回下载内容.GetResponseText方法有一个part参数,你要指定一个与在你的包里面的文件名相同的part名.

---

(4)Using the CreateFromXamlDownloader Method to Create XAML Content

---

CreateFromXamlDownloader方法按照在Downloader对象中使用的下载内容使用XAML动态的创建对象,只要能添加当前Silverlight对象,CreateFromXamlDownloader方法就会返回一个对象引用,你能创建一个单独的Silverlight对象,如TextBlock或Silverlight objects实体树.

CreateFromXamlDownloader 方法是一个创建XMAL对象的有效机制.除在同一函数中依次调用GetResponseText and CreateFromXaml外,它还避免从GetResponseText方法返回值中拷贝下载内容到一个临时缓存中再移交给XAML parser编译.可是CreateFromXamlDownloader 有一个限制不能暴露CreateFromXaml的参数createNameScope,这个参数允许你在创建新的对象时不连贯的命名范围.如果你需要创建新的对象时不连贯的命名范围,你应该依次调用GetResponseText and CreateFromXaml.详细的可以看 XAML Namescopes.

下面是JavaScript事例显示的是怎样通过使用CreateFromXamlDownloader方法为Canvas对象添加XAML内容.因为下载内容是使用的是包的方式,所以part参数设置为空字符串.

//  Event handler for the Completed event.
function  onCompleted(sender, eventArgs)
{
    // Retrieve a reference to the plug-in.
    var slPlugin = sender.getHost();

    // Retrieve the XAML fragment and create an object reference.
    // In this case, since the downloaded content represents a single file, OK_button.xaml,
    // the part parameter is set to an empty string.
    var xamlFragment = slPlugin.content.createFromXamlDownloader(sender, "");

    // Add the XAML object as a child of the root Canvas object.
    var root = sender.findName("rootCanvas");
    root.children.add(xamlFragment);
}

使用CreateFromXamlDownloader方法创建XAML内容不能呈现,直到它添加一个对象使用Add方法.下面图显示Silverlight object的层次结构和下载XAML内容在添加一个新的对象前后的关系.

你还能使用CreateFromXamlDownloader方法找回一个指定下载内容包中的part.当下载包为一个Zip文件时候,CreateFromXamlDownloader方法能找回ZIP文件中相应的文件名的文件.

下面JavaScript事例Show怎样使用CreateFromXamlDownloader方法,使用part参数引用指定的下载内容中的part.

JScript
Copy Code

//  Event handler for the Completed event.
function  onCompleted(sender, eventArgs)
{
    // Retrieve a reference to the plug-in.
    var slPlugin = sender.getHost();

    // Retrieve the specified XAML file from the packaged downloader content,
    // and create an object reference.
    var xamlFragment = slPlugin.content.createFromXamlDownloader(sender, "OK_button.xaml");

    // Add the XAML object as a child of the root Canvas object.
    var root = sender.findName("rootCanvas");
    root.children.add(xamlFragment);
}

---

(5)Using the SetSource Method to Set Media Content

---

SetSource方法能通过设置MediaElement的Source属性设置下载的media内容.相同的方法还有现有的Image和ImageBrush.SetSource方法的第一个参数是用来识别Downloader对象当前呈现的下载内容.第二个参数是识别指定内找下载内容内的part.如果下载内容呈现包的形式,如一个.Zip文件,第二个参数就必须设置为空字符串.
下面是JavaScript事例 Show的是怎样使用SetSource方法去设置Image对象的Source属性.

//  Event handler for the Completed event.
function  onCompleted(sender, eventArgs)
{
    // Retrieve the Image object.
    var myImage = sender.findName("myImage");

    // Set the Source property to the contents of the downloaded object,
    // In this case, since the downloaded content represents a single image file, promo.png,
    // the part parameter is set to an empty string.
    myImage.setSource(sender, "");
}

你还能使用SetSource方法找回在下载内容包中指定一个part.当下载内容包为.zip文件时.SetSource方法允许你找回在.zip文件内的一个相同文件名的内容.
如下面是使用SetSource方法设置一个Image对象的Source属性去指定下载内容中的part.

function  onDownloadCompleted(sender, eventArgs)
{
    // Retrieve the XAML content from the downloaded package file.
    var jacketBrowserXaml = sender.getResponseText("jacketBrowser.xaml");
    // Create the objects from the XAML content.
    var jacketBrowser = plugin.content.createFromXaml(jacketBrowserXaml);

    // Add downloaded XAML content to the root Canvas of the plug-in.
    sender.findName("root").children.insert(0, jacketBrowser);

    // Retrieve a reference to the Image object representing the jacket.
    var jacketImageSlice = sender.findName("jacketSlice");

    // Set the Source property of the Image object to the specific jacket image
    // within the downloaded Zip package file.
    jacketImageSlice.setSource(sender, "rotation01_green.png");
}

---

(6)Using SetFontSource for Downloaded Fonts

---

SetFontSource 方法能为TextBlock对象现有字体添加下载字体.downloader参数识别Downloader对象.下载内容可能是单个的文字文件也有可能是一个包,如.zip文件.

注意:字体文件使用SetFontSource方法必须是OpenType或TrueType字体,并且必须有文件扩展为.ttf.

在下面是JavaScirpt的example Show的是怎样使用Downloader对象去下载一个单个字体文件。

//  Event handler for initializing and executing a font file download request.
function  onMouseLeftButtonUp(sender, eventArgs)
{
    // Retrieve a reference to the plug-in.
    var plugin = sender.getHost();

    // Create a Downloader object.
    var downloader = plugin.createObject("downloader");

    // Add Completed event.
    downloader.addEventListener("Completed", onCompleted);

    // Initialize the Downloader request. Note that the font name referenced in this sample is fictitious.
    downloader.open("GET", "contoso.TTF");

    // Execute the Downloader request.
    // NOTE: downloader APIs disallow file:\\ scheme
    // you must run this sample over localhost: or off a server or the following call will fail
    downloader.send();
}

当字体文件已经被下载，它需要被添加到TextBlock的字体集合里面。当它已经添加到集合里面，它就能被FontFamily属性所使用。下面是事例怎样使用SetFontSource 方法添加字体文件到字体集合中，并被FontFamily属性使用显示在TextBlock。

//  Event handler for the Completed event.
function  onCompleted(sender, eventArgs)
{
    // Retrieve the TextBlock object.
    var myTextBlock = sender.findName("myTextBlock");

    // Add the font files in the downloaded object to the TextBlock's type face collection.
    myTextBlock.setFontSource(sender);

    // Set the FontFamily property to the friendly name of the font.
    // This sample uses a fictitious font called "Contoso Font".
    myTextBlock.fontFamily = "Contoso Font";

    myTextBlock.text = "This is my new font!";
}

你还能将下载字体包含在一个包中一起被下载，如一个.zip文件。这个.zip文件中还能包含其他文件，如image文件。

下面是怎样使用Downloader对象下载包含一个image文件和多个文字文件的.zip文件。

//  Initialize the Downloader request. Zip file contains
//  font files, image files, etc.
downloader.open( " GET " ,  " myMediaAssets.zip " );

当.zip文件下载已经被下载，字体文件必须被添加到TextBlock的字体文件集合。字体文件一经添加到集合里面，他们就被FontFamily属性选种。下面是JavaScript的example，Show的是使用SetSource和SetFontSource方法去使用下载内容；

//  Event handler for the Completed event.
function  onCompleted(sender, eventArgs)
{
    // Retrieve the Image object.
    var myImage = sender.findName("myImage");

    // Set the Source property of the Image object to the specific image
    // within the downloaded Zip package file.
    myImage.setSource(sender, "MyImage.png");

    // Retrieve the TextBlock object.
    var myTextBlock = sender.findName("myTextBlock");

    // Add the font files in the downloaded package object to the TextBlock's type face collection.
    myTextBlock.setFontSource(sender);

    // Set the FontFamily property to the friendly name of the font.
    myTextBlock.fontFamily = "Contoso Font";
}

TextBlock返回的是默认的字体，就将SetFontSource 方法的downloader参数设置为null。
下面是怎样使用参数为null的SetFontSource方法。

//  Retrieve the TextBlock object.
var  myTextBlock  =  sender.findName( " myTextBlock " );

//  Remove the custom font setting.
myTextBlock.setFontSource( null );

---

（7）Handling Downloader Errors

---

有两个互斥事件，一个是报告下载成功，一个是报告下载失败。有Completed (success)和DownloadFailed (failure)，特别是你要为这个两个事件写事件函数。

Status和StatusText属性提供HTTP状态码和结合文本字符串形式来显示Downloader object下载请求。通常而言，状态为”200“为（成功）为Completed handler，204为DownloadFailed handler（没有下载内容）。

---

（8）Using the Abort Method
在这里有更多描述
（9）URI Protocols and Schemes  
在这里有更多描述     
see URL Access Policy.     



------------ worksguo翻译