widget中文技术文档

Version 3.1.1 版
2006 年 4 月 14 日
 
著作权 2002-2006 Yahoo! Inc.
保留所有权利
 
版本历史
第一次发行
第二次发行
第三次发行
第四次发行
第五次发行
第六次发行
第七次发行
第八次发行
第九次发行
第十次发行
第十一次发行
第十二次发行
第十三次发行
第十四次发行
第十五次发行
第十六次发行
第十七次发行
 
 
 
 
1.5 版
1.5.1 版
1.6.2 版
1.8 版
1.8.1 版
1.8.3 版
2.1 版
2.1.1 版
3.0 版
3.0.x 版
3.1 版
3.1.1 版
2003 年 2 月 10 日
2003 年 2 月 12 日
2003 年 2 月 15 日
2003 年 2 月 19 日
2003 年 7 月 23 日
2003 年 9 月 26 日
2003 年 10 月 8 日
2004 年 6 月 6 日
2004 年 11 月 8 日
2004 年 11 月 24 日
2005 年 1 月 18 日
2005 年 7 月 23 日
2005 年 8 月 3 日
2005 年 12 月 7 日
2006 年 1 月 6 日
2006 年 3 月 30 日
2006 年 4 月 14 日
 
 
谨在此向所有参与修改和提出宝贵意见的人们致谢。
 
本产品包含由 OpenSSL Project 项目组开发用于 OpenSSL Toolkit 的软件。
( http://www.openssl.org/)
 
 
 
 

Yahoo! Widget Engine 基本介绍
Yahoo! Widget Engine (或简称为 'Widget Engine'，在本文中有时会简称为 'engine') 使用 XML
来定义 Widget工具 (以下在本文中会简称为 ‘Widget’)以及组成它们的对象。这可使对象的层次
更清楚。
 
一个简单的 Widget ：


main_window
500
500
 

250
250
center

 

text1
250
100 center

sun1.opacity = (sun1.opacity / 100) * 90;




 
它所做的事情，就是在用户点击「点击这里」的文字时，将图片透明度降低 10%。这并不是十分
有用的范例，但是我们用这个简单的范例来说明一些重要内容。这个范例需要一个外部文件，即
Images/Sun.png，如果在缺少该文件的情况下执行，将会显示「缺少图片」的符号。
首先，请注意 Widget 的结构：XML 是一种对称式语言，其中每个对象 (例如 ) 都有与
之对应的结束标签 ()。如屏幕位置、对齐等对象属性皆可在这些结构组中定义。另请注意，
在 XML 中定义的对象 (例如 sun1) 可以在 JavaScript 中操作 (参见 text1 对象中的 onMouseDown
句柄)。对象名称必须以字母开头，且只允许字母、数字与下划线。Widget 的 XML 会以后缀名为 .kon
的文件存放 (关于此文件所在包的讨论信息，请参见以下信息)。
实际的 Widget 可以含有许多图片与文字、多个 JavaScript 区段 (通常在外部文件中)，而且可
以在运行过程中建立新对象，并使用 JavaScript 来实现复杂的功能。
显然，制作 Yahoo! Widget 的最轻松的方法就是获得现有的 Widget，并对其进行修改。
 
 
基础
我们有功能强大的 XML 解析器，这表示可以使用标签批注样式或混合搭配样式。这两种样式是：


images/image.png
myImage

 
或：

 
混合搭配也不错：

myImage

 
实体
实体是通过特殊字符序列来代表另一个字符的 XML 结构。
&
&
"
"
&apos:
'
<
<
>
>
 
也可以依照其 unicode 字码，使用实体来指定字符：


这些实体只能在 2.1 版或更高版本中使用。XML 引擎会寻找 < 和 > 符号以标记 XML 数据的标
签，我们的 JavaScript 引擎需要以 < 和 > 来分别取代这些符号。例如：

if (x < 5)
displayResults();

也可以采用 HTML 中的作法，使用 XML 批注来对 XML 引擎隐藏 JavaScript 程序代码，如下所
示：

 if (x < 5)
 displayResults();
//-->

 
这是惯用的作法，因为它可以让程序代码更清晰可读。
在 2.1 版或更高版本中，可以使用 CDATA 区段：

if (x < 5)

displayResults();
]]>

 
也可以应用外部 JavaScript，我们稍后将会介绍这个部分。
 
严格模式 (Strict Mode)
在 2.1 版或更高版本中，可以将 XML 解析器设定为「严格」模式。这表示它将会采用某些过去
未曾使用的方式来强制执行 XML 规则。实际上，它在许多方面都不是很严格的。要启用此模式，只需
将以下这一行加到 XML 文件的上方即可：
 

 
在严格模式下，将会强制执行以下操作：
1) 所有的属性值都必须加上引号。
2) 文字区段中不允许使用单独的 "&" 字符 (只能是这样的形式 &)。
3) 实体 (以 "&" 开头的字符串) 的属性值会被评估。
4) 批注中不允许使用双横线 ("--")。因此最好将程序代码放进 CDATA 标签中。
5) 如果包含了外部文件，不会在该文件中替代 < 等实体。
CDATA 标签适用于 2.1 版或更高版本。
 
文件路径 (File Paths)
引擎中的文件路径总是与 XML 文件的位置相关。这表示未指定目录的文件 (例如 main.js) 在
XML 文件所在的目录中寻找，而指定了目录的文件 (例如 javascript/main.js) 在 XML 文件所在目
录的子目录中寻找。不建议使用绝对路径 (以 / 开头的路径)，因为用户机器的磁盘配置可能会有明
显的差异。
 
Widget 封装 (Widget Packaging)
在 Windows 上，组成 Widget 的文件存放在 .widget 文件中。这是一个已经将其后缀名改
为 .widget 的标准 ZIP 文件。
无论在 Windows 上或是在 Mac OS X 上，.widget 包皆有以下结构：
myWidget.widget
Contents
myWidget.kon
Resources


.kon 文件包含 Widget 的程序代码 (与以上部分中的范例 Widget 相似)。目前 .kon 文件必须
包含在被称为 Contents 的文件夹中。可以将图片等资源放到任何地方，但是它们通常会被放到
Resources 文件夹中，如上所示。
如果不使用 Widget converter 封装 Widget，而是手动压缩它们，在 PC 上最好的操作方式是
在 .widget 文件夹上点击鼠标右键，选择从该处建立 ZIP 文件。在 Mac 上，可以使用例如 DropZip
之类的程序。
请注意，开发 Widget 时，不需要在每次进行改变时都建立新的 Widget 压缩包，只需要双击 .kon
文件即可。
不可以在执行期间修改 Widget 。也就是说，请勿将信息存放在 Widget 自身中。虽然大多数
Widget 都使用偏好设置来存放它们的设定值，但是仍然有一些 Widget 将信息存放在它自身中。当
Widget Engine 执行压缩的 Widget 时，它首先会将其解压缩到一个特定的位置，然后从该处执行它。
在最近的版本中，这个解压缩的动作会在每次执行 Widget 时进行，因此，如果将信息存放在 Widget
中，就会丢失该信息。存放永久性数据可以使用 system.widgetDataFolder。
 
Flat-File 封装格式 (Flat-File Format)
从 3.1 版开始，引擎支持非 zip 的 flat-file 格式。zip 解决方案不仅有性能方面的问题 (特
别是在 3.0 中)，还会产生其它一些麻烦。
现在，新格式的 Widget并不被压缩，因此 Widget 的大小在这种格式之下会比 zip 格式要大。
但是，由于图片占据了 Widget 绝大部分的大小，增加的大小平均约为 10-15%，因为图片通常已是压
缩格式 (PNG、JPG)，而文本则不然。文件不会刻意压缩，这样就可以对文件进行文件映射，在真正需
要用到之前，不需要将所有内容加载进内存 。
由于有了这种新格式，Widgets 3.1 的启动速度比 3.0 要快多了。要使用这种新格式，必须用到
Widget Converter。
对于 flatfile 格式，除非使用新的 API (widget.extractFile()) 来将文件从 flat-file Widget
中释放到文件系统中，否则将无法使用 dll 等随 Widget 一起封装的项目。但是，通过 play() 函数
播放的声音文件仍可正常使用。
Widget Runtime
将Widget 做为独立的程序运行，这可以确保一个 Widget 出问题时不会影响到其它 Widget。
压缩的 Widget 将会解压缩至特定位置 (Mac 上为 /tmp，PC 上为 C:/Documents and
Settings//Local Settings/Application Data)。未压缩的 Widget 则会直接在其所在位置上
执行。当我们在 Widget 中找到 .kon 文件时，可以将当前目录设定为找到 .kon 文件的目录。举例
来说，如果 .kon 文件如同往常般在 Contents 文件夹中，当前的工作目录就是 Contents，这样相
对路径才可以正确使用。如果 .kon 文件的图片位于 Contents 底下的 Resources 文件夹中，.kon 文
件便可以像这样应用图片 Resources/Image1.png。
找到 .kon 文件，且当前工作目录也设定好了之后，文件会被解析，并且建立程序中定义的对象。
所有项目都成功建立好了之后会调用 onLoad 句柄 (参见 'action' 对象说明文件)。此时， Widget 便
可以进行初始化了。成功执行了 onLoad 之后， Widget 便开始执行了！
Widget 将会在下一次执行时再次解压缩。因此你无法在 Widget 包中存放信息，请将需要存储的
信息放至的 widgetDataFolder。
Widget Engine 将自动记录打开了哪些 Widget。下一次启动引擎时，它将会重新打开上一次结束

时正在运行的 Widget。
动作 (Actions)
动作是 Widget 的命脉。它定义用户与 Widget 交互的情况下，Widget 将做些什么。在 3.0 版
之前的版本中，指定动作的唯一方法是将动作设定为某些 Javascript 代码，这些代码会在用户点击
鼠标左键时被检查，执行，例如：

print( "hello" );

 
有如下限制
a) 不可以使用 Javascript 的 'this' 来引用当前的对象
b) 如果有数个含有相同代码的对象，必须改变对象名称，以区分程序代码的每个对象。
为了修正此类情况，在 3.0 版或更高版本中，引擎支持在动作中调用Javascript 函数。在 3.0
版中，不可以把参数传给动作，但在未来的版本中应该支持传送参数。例如，onMouseUp 句柄接收鼠
标的 x 与 y 坐标，而不用再检查 system.event。
可以使用属性 (而且必须是属性，不能用子元素)，或在 Javascript 中设定要调用的函数的属性
来告知引擎你想要调用的函数：
 


// 在 Javascript 中
myImage.onMouseUp = _myMouseUp;
// 在你 JS 程序代码的某处，必须定义函数：
function _myMouseUp()
{
print( this.opacity );
}
对象名称 (Object Names)
可以在 XML 描述中设定 属性。 这将会定义全局 Javascript 对象，它将被并绑定至名
称为其前缀名的对象。例如：

因为这些名称是在内部用来跟踪对象的，因此不应改变，3.0 版将所有名称属性强制为只读来达
到此目的。
调试 (Debugging)
当设定debug标签为 “on ”时，调试窗口会在运行 Widget 时显示。在 JavaScript 程序代码

中调用 log() 或 print() 将会把调试信息传送至此窗口。Widget Engine 或 Widget 中所发生的任
何错误也将会在此窗口中显示。
开发 Widget 时，应该始终将调试功能打开，以便使了解到可能发生的错误。例如，如果将某个
属性拼错了，调试窗口将会显示错误，并给出程序代码中出现问题的位置。
请注意，特别是在 PC 上，除非将调试设定为打开，否则调试窗口将永远不会打开。
在 2.1 版及更高版本中，可以按住 control 与 shift 按键，然后在菜单中选择「工具」菜单来
打开调试模式。当选择此选项之后，启动的任何 Widget 都将会强制打开调试窗口。因此，不需要再
在 Widget 中使用调试标签。也可以让用户使用此模式来诊断问题的所在。
 
另外在 2.1 版或更高版本中，调试功能已通过新的命令行字段来增强。可以在此字段中发出命令
(在字段中键入 "/help" 来显示完整的清单) 或只是简单评估一些 JavaScript。这对于检查变量值等
工作是很方便的，也可以使用内置命令来跟踪变量与函数。
 
异常 (Exceptions)
从 2.0 版开始，Widget Engine 会在发生错误时产生异常。了解并在适当的地方使用 try/catch
句柄非常重要，这对于 COM 是必须的，它可以帮你摆脱并处理联机失败等情形。Day Planner Widget
将会在其 Outlook 处理中使用 try/catch。
Widget 偏好设置 (Widget Preferences)
Widget 提供一些存放设定值的对象。这些设定值存放在每个用户的偏好设置区域中。在 Mac 上，
此设定值位于 ~/ Library/Preferences/Konfabulator 中。在 PC 上，此设定值位于
HKEY_CURRENT_USER/ Software/Yahoo/WidgetEngine 中。
最低版本需求 (MinimumVersion)
的最低版本属性会通知引擎哪个版本的引擎才能执行该 Widget。但是从 3.0 版开始，
它也会通知引擎此 Widget 已针对 3.0 版进行修订，而就其本身而言，我们将可以使用它来改变
Widget的某些行为。
如果将最低版本需求设定为 3.0，应注意以下事项：
1) 视图不会自动绑定至默认窗口。以前情况或许是如此，但是随着 3.0 版中层次视图的出现，
这将会出问题，必须指定对象所属的窗口，或使用 frame.addSubview() 来将对象内嵌至框体中。如
果接口大部分由 XML 结构实现，那么你只需要将 image/text/frame/scrollbar/textarea 对象置于
窗口对象中即可：








将 Widget 升级到 3.0 版时可能会发生的最常见错误就是一些视图没有显示出来。这都是因为这
个行为的改变所造成的。你只需反复检查所有的视图是否皆已绑定至某些窗口或父框体即可。
 
2) Javascript 有效生存期的改变。在之前的版本中，调用对象上的删除或将它设定为空将会使
对象从窗口中消失。而现在如果要移除对象，必须调用