flash.media.Sound (Flex 3)

	属性	定义方
		bytesLoaded : uint [只读 (read-only)] 返回此声音对象中当前可用的字节数。	Sound
		bytesTotal : int [只读 (read-only)] 返回此声音对象中总的字节数。	Sound
		constructor : Object 对类对象或给定对象实例的构造函数的引用。	Object
		id3 : ID3Info [只读 (read-only)] 提供对作为 MP3 文件一部分的元数据的访问。	Sound
		isBuffering : Boolean [只读 (read-only)] 返回外部 MP3 文件的缓冲状态。	Sound
		length : Number [只读 (read-only)] 当前声音的长度（以毫秒为单位）。	Sound
		prototype : Object [静态] 对类或函数对象的原型对象的引用。	Object
		url : String [只读 (read-only)] 从中加载此声音的 URL。	Sound

	方法	定义方
		Sound(stream:URLRequest = null, context:SoundLoaderContext = null) 创建一个新的 Sound 对象。	Sound
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。	EventDispatcher
		close():void 关闭该流，从而停止所有数据的下载。	Sound
		dispatchEvent(event:Event):Boolean 将事件调度到事件流中。	EventDispatcher
		hasEventListener(type:String):Boolean 检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指示对象是否已经定义了指定的属性。	Object
		isPrototypeOf(theClass:Object):Boolean 指示 Object 类的实例是否在指定为参数的对象的原型链中。	Object
		load(stream:URLRequest, context:SoundLoaderContext = null):void 启动从指定 URL 加载外部 MP3 文件的过程。	Sound
		play(startTime:Number = 0, loops:int = 0, sndTransform:SoundTransform = null):SoundChannel 生成一个新的 SoundChannel 对象来回放该声音。	Sound
		propertyIsEnumerable(name:String):Boolean 指示指定的属性是否存在、是否可枚举。	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 从 EventDispatcher 对象中删除侦听器。	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 设置循环操作动态属性的可用性。	Object
		toString():String 返回指定对象的字符串表示形式。	Object
		valueOf():Object 返回指定对象的原始值。	Object
		willTrigger(type:String):Boolean 检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器。	EventDispatcher

摘要	定义方
activate	Flash Player 或 AIR 应用程序获得操作系统焦点并变为活动状态时调度。	EventDispatcher
complete	成功加载数据后调度。	Sound
deactivate	Flash Player 或 AIR 应用程序失去操作系统焦点并变为非活动状态时调度。	EventDispatcher
id3	在存在可用于 MP3 声音的 ID3 数据时由 Sound 对象调度。	Sound
ioError	在出现输入/输出错误并由此导致加载操作失败时调度。	Sound
open	在加载操作开始时调度。	Sound
progress	在加载操作进行过程中接收到数据时调度。	Sound

属性详细信息

bytesLoaded

属性

bytesLoaded:uint [只读 (read-only)]

返回此声音对象中当前可用的字节数。这通常只对从外部加载的文件有用。

bytesTotal

属性

bytesTotal:int [只读 (read-only)]

返回此声音对象中总的字节数。

id3

属性

id3:ID3Info [只读 (read-only)]

提供对作为 MP3 文件一部分的元数据的访问。

MP3 声音文件可以包含 ID3 标签，ID3 标签提供有关该文件的元数据。如果使用 Sound.load() 方法加载的 MP3 声音包含 ID3 标签，则可以查询这些属性。只支持使用 UTF-8 字符集的 ID3 标签。

AIR 运行时支持 ID3 2.0 标签，特别是 2.3 和 2.4。以下各表列出了标准 ID3 2.0 标签以及这些标签所表示内容的类型。Sound.id3 属性通过 my_sound.id3.COMM 和 my_sound.id3.TIME 等格式提供对这些标记的访问权限。第一个表描述了可通过 ID3 2.0 属性名称或 Sound 类属性名称进行访问的标签。第二个表描述了在 Sound 类中受支持但不具有预定义属性的 ID3 标签。

ID3 2.0 标签	相应的 Sound 类属性
COMM	Sound.id3.comment
TALB	Sound.id3.album
TCON	Sound.id3.genre
TIT2	Sound.id3.songName
TPE1	Sound.id3.artist
TRCK	Sound.id3.track
TYER	Sound.id3.year

下表描述了在 Sound 类中受支持但不具有预定义属性的 ID3 标签。通过调用 mySound.id3.TFLT 和 mySound.id3.TIME 等来访问它们。

属性	Description
TFLT	文件类型
TIME	时间
TIT1	内容组说明
TIT2	标题/歌曲名称/内容说明
TIT3	副标题/说明精选
TKEY	初始密钥
TLAN	语言
TLEN	长度
TMED	媒体类型
TOAL	原始唱片/影片/演出标题
TOFN	原始文件名
TOLY	原词作者/乐谱作者
TOPE	原始艺术家/表演者
TORY	原始发行年份
TOWN	文件所有者/获得授权者
TPE1	主要表演者/独奏（独唱）
TPE2	乐队/管弦乐队/伴奏
TPE3	指挥/主要演奏者
TPE4	翻译、混录员或以其它方式进行修改的人员
TPOS	歌曲集部分
TPUB	发行者
TRCK	歌曲集中的曲目编号/位置
TRDA	录制日期
TRSN	Internet 无线电台名称
TRSO	Internet 无线电台所有者
TSIZ	大小
TSRC	ISRC（国际标准音像制品编码）
TSSE	用于编码的软件/硬件和设置
TYER	年份
WXXX	URL 链接帧

在使用此属性时，请考虑以下安全模型：

对于与声音文件位于同一安全沙箱的文件，始终允许 Sound 对象的 id3 属性。对于其它沙箱中的文件，则需经过安全检查。
使用 Sound 类的 load() 方法加载声音时，可指定 context 参数，该参数为一个 SoundLoaderContext 对象。如果将 SoundLoaderContext 对象的 checkPolicyFile 属性设为 true，则应用程序将在从其中加载该声音的服务器上检查跨域策略文件是否存在。如果有跨域策略文件，且该文件允许正在加载的文件的域，那么，将允许该文件访问 Sound 对象的 id3 属性，否则就不允许。

但在 Adobe AIR 中，application 安全沙箱中的内容（使用 AIR 应用程序安装的内容）不受这些安全限制的约束。

有关详细信息，请参阅以下部分：

Flash Player 9 Security 白皮书

另请参见

SoundLoaderContext.checkPolicyFile

isBuffering

属性

isBuffering:Boolean [只读 (read-only)]

返回外部 MP3 文件的缓冲状态。如果值为 true，则在对象等待获取更多数据时，当前将会暂停任何回放。

length

属性

length:Number [只读 (read-only)]

当前声音的长度（以毫秒为单位）。

url

属性

url:String [只读 (read-only)]

从中加载此声音的 URL。此属性只适用于使用 Sound.load() 方法加载的 Sound 对象。对于与 SWF 文件库中的声音资源关联的 Sound 对象，url 属性的值为 null。

首次调用 Sound.load() 时，url 属性最初具有 null 值，因为最终 URL 未知。只要从 Sound 对象中调度了 open 事件，url 属性就会具有非空值。

url 属性包含已从其中加载了声音的最终、绝对 URL。url 的值通常与传递给 Sound.load() 的 stream 参数的值相同。但是，如果已将相对 URL 传递给 Sound.load()，则 url 属性的值将表示绝对 URL。此外，如果 HTTP 服务器重定向原始 URL 请求，url 属性的值将反映从其中实际下载声音文件的最终 URL。这种报告绝对、最终 URL 的行为与 LoaderInfo.url 的行为等效。

另请参见

Sound.load()

构造函数详细信息

Sound

()

构造函数

function Sound(stream:URLRequest = null, context:SoundLoaderContext = null)

创建一个新的 Sound 对象。如果将有效的 URLRequest 对象传递到 Sound 构造函数，该构造函数将自动调用 Sound 对象的 load() 函数。如果未将有效的 URLRequest 对象传递到 Sound 构造函数，则必须自己调用 Sound 对象的 load() 函数，否则将不加载流。

一旦对某个 Sound 对象调用了 load()，就不能再将另一个声音文件加载到该 Sound 对象中。若要加载另一个声音文件，请创建新的 Sound 对象。

参数

	`stream:URLRequest` (default = `null`) — 指向外部 MP3 文件的 URL。

	`context:SoundLoaderContext` (default = `null`) — 一个可选的 SoundLoader 上下文对象，可以定义缓冲时间（MP3 数据保留到 Sound 对象的缓冲区中所需的最小毫秒数）并且可以指定加载声音前应用程序是否应该检查跨域策略文件。

方法详细信息

()

方法

function close():void

关闭该流，从而停止所有数据的下载。调用 close() 方法之后，将无法从流中读取数据。

引发

IOError — 无法关闭该流，或者该流未打开。

load

()

方法

function load(stream:URLRequest, context:SoundLoaderContext = null):void

启动从指定 URL 加载外部 MP3 文件的过程。如果为 Sound 构造函数提供有效的 URLRequest 对象，该构造函数将为您调用 Sound.load()。只有在未将有效的 URLRequest 对象传递到 Sound 构造函数或传递了 null 值的情况下，才需要自己调用 Sound.load()。

一旦对某个 Sound 对象调用了 load()，就不能再将另一个声音文件加载到该 Sound 对象中。若要加载另一个声音文件，请创建新的 Sound 对象。

在使用此方法时，请考虑以下安全模型：

如果执行调用的文件在只能与本地文件系统的内容交互的沙箱中，并且声音在网络沙箱中，则不允许调用 Sound.load()。
从受信任的本地沙箱或只能与远程内容交互的沙箱进行访问需要通过跨域策略文件获得网站的许可。
可以在包含内容的 HTML 页中设置 object 和 embed 标签的 allowNetworking 参数，防止 SWF 文件使用此方法。

在 Adobe AIR 中，application 安全沙箱中的内容（使用 AIR 应用程序安装的内容）不受这些安全限制的约束。

有关详细信息，请参阅以下部分：

“安全性”一章（位于《ActionScript 3.0 编程》一书中）和有关 LiveDocs 的最新评论
Developing AIR Applications（《开发 AIR 应用程序》）一书的“Getting started with Adobe AIR”（Adobe AIR 入门）一章中的“Understanding AIR Security”（了解 AIR 安全性）一节。
Flash Player 9 Security 白皮书

参数

	`stream:URLRequest` — 指向外部 MP3 文件的 URL。

	`context:SoundLoaderContext` (default = `null`) — 一个可选的 SoundLoader 上下文对象，可以定义缓冲时间（MP3 数据保留到 Sound 对象的缓冲区中所需的最小毫秒数）并且可以指定加载声音前应用程序是否应该检查跨域策略文件。

引发

	`IOError` — 网络错误导致加载失败。

	`SecurityError` — 本地不受信任的文件可能无法与 Internet 进行通信。可通过将此文件重新分类为只能与远程内容交互或受信任来解决此问题。

另请参见

Flash Player security

play

()

方法

function play(startTime:Number = 0, loops:int = 0, sndTransform:SoundTransform = null):SoundChannel

生成一个新的 SoundChannel 对象来回放该声音。此方法返回 SoundChannel 对象，访问该对象可停止声音并监控音量。（若要控制音量、平移和平衡，请访问分配给声道的 SoundTransform 对象。）

参数

	`startTime:Number` (default = `0`) — 应开始回放的初始位置（以毫秒为单位）。

	`loops:int` (default = `0`) — 定义在声道停止回放之前，声音循环回 `startTime` 值的次数。

	`sndTransform:SoundTransform` (default = `null`) — 分配给该声道的初始 SoundTransform 对象。

SoundChannel — SoundChannel 对象，用于控制声音。如果没有声卡或用完了可用的声道，此方法将返回 null。一次最多可以使用 32 个声道。

另请参见

SoundChannel.stop()
SoundMixer.stopAll()

事件详细信息

complete

事件

事件对象类型: flash.events.Event
属性 Event.type = flash.events.Event.COMPLETE

成功加载数据后调度。

Event.COMPLETE 常量定义 complete 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	已完成加载的网络对象。

另请参见

Sound.load()

id3

事件

事件对象类型: flash.events.Event
属性 Event.type = flash.events.Event.ID3

在存在可用于 MP3 声音的 ID3 数据时由 Sound 对象调度。

Event.ID3 常量定义 id3 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	加载 MP3 的 Sound 对象，ID3 数据现在可用于此对象。`target` 不一定是显示列表中注册此事件侦听器的对象。请使用 `currentTarget` 属性来访问显示列表中当前正在处理此事件的对象。

另请参见

Sound.id3

ioError

事件

事件对象类型: flash.events.IOErrorEvent
属性 IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR

在出现输入/输出错误并由此导致加载操作失败时调度。

定义 ioError 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`errorID`	与特定错误关联的引用数字。
`target`	发生输入/输出错误的网络对象。
`text`	要显示为错误消息的文本。

另请参见

Sound.load()

open

事件

事件对象类型: flash.events.Event
属性 Event.type = flash.events.Event.OPEN

在加载操作开始时调度。

Event.OPEN 常量用于定义 open 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	已打开连接的网络对象。

另请参见

Sound.load()

progress

事件

事件对象类型: flash.events.ProgressEvent
属性 ProgressEvent.type = flash.events.ProgressEvent.PROGRESS

在加载操作进行过程中接收到数据时调度。

定义 progress 事件对象的 type 属性值。

此事件具有以下属性：

属性	值
`bubbles`	`false`
`bytesLoaded`	在侦听器处理事件时加载的项数或字节数。
`bytesTotal`	如果加载进程成功，最终将加载的项目或字节总数。
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	报告进度的对象。

另请参见

Sound.load()

示例

SoundExample.as

以下示例显示有关打开并播放 MP3 文件时发生的声音事件的信息。

注意：要测试此示例，请执行以下操作：

将 AIRAliases.js 文件添加到项目目录。
将一个名为 MySound.mp3 的文件放在同一项目目录中。
为该项目创建应用程序描述符文件，并使用 ADL 测试该项目。

<html>
    <head>
      <script src="AIRAliases.js" />
      <script>
        function init() {
            var request = new air.URLRequest("app://MySound.mp3");
            var soundFactory = new air.Sound();
            soundFactory.addEventListener(air.Event.COMPLETE, completeHandler);
            soundFactory.addEventListener(air.Event.ID3, id3Handler);
            soundFactory.addEventListener(air.IOErrorEvent.IO_ERROR, ioErrorHandler);
            soundFactory.addEventListener(air.ProgressEvent.PROGRESS, progressHandler);
            soundFactory.load(request);
            song = soundFactory.play();
        }

        function completeHandler(event) {
            air.trace("completeHandler: " + event);
        }

        function id3Handler(event) {
            air.trace("id3Handler: " + event);
        }

        function ioErrorHandler(event) {
            air.trace("ioErrorHandler: " + event);
        }

        function progressHandler(event) {
            air.trace("progressHandler: " + event);
        }
      </script>
    </head>
    <body onload='init()'>
    </body>
</html>

window.runtime 属性	window.runtime.flash.media.Sound

继承	Sound EventDispatcher Object

针对 HTML 开发人员的 Adobe AIR 语言参考	索引 \| 框架无框架
Sound