这是一个在javascript中构建XPCOM组件"hello world"的教程。这个教程不会描述XPCOM是怎么工作或者为什么那么工作，也不打算对每一部分代码进行解释。这个会在其他文章里面祥述elsewhere. 这个教程展示给你用最少的步骤来完成一个能工作的组件的过程。
Caveat: This was done on a Mac. YMMV with Windows.
实现
这个组件将会公开一个方法，他返回"Hello World!".
定义接口
如果你想在JavaScript中用你的接口, 或者从其他 XPCOM components中调用, 你要定义一个公开接口 (如果你的组件仅仅用在Javascript中, 你可以使用 wrappedJSObject 技巧来避免这里所建立的接口. 参看 here 上的例子).
Mozilla应用中已经定义了很多接口，你可能不必再定义一个. 你可以浏览现有的Mozilla源代码里面的XPCOM接口，或者使用XPCOMViewer, 他是一个浏览注册接口和组件的GUI工具. 你可以下载旧的跟Firefox 1.5匹配的viewer，在mozdev mirrors.
如果一个现存的接口满足你的要求，那你就不需要再写一个IDL, 编译typelib, 可以直接跳过下一节 next section.
如果你没有发现现有的合适的接口，那你就要定义一个自己的。XPCOM使用一个IDL的修订版来定义接口, 叫做XPIDL. 这里有一个XPIDL对HelloWorld组件的定义:
HelloWorld.idl
#include "nsISupports.idl"
[scriptable, uuid(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)]
interface nsIHelloWorld : nsISupports
{
string hello();
};
注意你要为每一个XPCOM组件建立一个UUID。参看Generating GUIDs。
编译 Typelib
你的接口定义必须编译成为二进制(XPT)以便于注册和在Mozilla应用中使用。编译可以利用Gecko SDK. Windows and Linux versions 的SDK可以从wiki.mozilla.org获取. 我编译了一个Mac version的SDK (1.8 branch, OS X PPC 10.4), 暂时放在 here.
执行下面的命令来编译typelib. 其中, <tt>{sdk_dir}</tt>是你放置Gecko SDK的目录.
{sdk_dir}/bin/xpidl -m typelib -w -v -I {sdk_dir}/idl -e HelloWorld.xpt HelloWorld.idl
这将会在当前目录建立一个typelib文件HelloWorld.xpt.
建立组件
HelloWorld.js
/***********************************************************
constants
***********************************************************/
// reference to the interface defined in nsIHelloWorld.idl
const nsIHelloWorld = Components.interfaces.nsIHelloWorld;
// reference to the required base interface that all components must support
const nsISupports = Components.interfaces.nsISupports;
// UUID uniquely identifying our component
// You can get from: https://kruithof.xs4all.nl/uuid/uuidgen here
const CLASS_ID = Components.ID("{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx}");
// description
const CLASS_NAME = "My Hello World Javascript XPCOM Component";
// textual unique identifier
const CONTRACT_ID = "@dietrich.ganx4.com/helloworld;1";
/***********************************************************
class definition
***********************************************************/
//class constructor
function HelloWorld() {
};
// class definition
HelloWorld.prototype = {
// define the function we want to expose in our interface
hello: function() {
return "Hello World!";
},
QueryInterface: function(aIID)
{
if (!aIID.equals(nsIHelloWorld) &&
!aIID.equals(nsISupports))
throw Components.results.NS_ERROR_NO_INTERFACE;
return this;
}
};
/***********************************************************
class factory
This object is a member of the global-scope Components.classes.
It is keyed off of the contract ID. Eg:
myHelloWorld = Components.classes["@dietrich.ganx4.com/helloworld;1"].
createInstance(Components.interfaces.nsIHelloWorld);
***********************************************************/
var HelloWorldFactory = {
createInstance: function (aOuter, aIID)
{
if (aOuter != null)
throw Components.results.NS_ERROR_NO_AGGREGATION;
return (new HelloWorld()).QueryInterface(aIID);
}
};
/***********************************************************
module definition (xpcom registration)
***********************************************************/
var HelloWorldModule = {
_firstTime: true,
registerSelf: function(aCompMgr, aFileSpec, aLocation, aType)
{
aCompMgr = aCompMgr.
QueryInterface(Components.interfaces.nsIComponentRegistrar);
aCompMgr.registerFactoryLocation(CLASS_ID, CLASS_NAME,
CONTRACT_ID, aFileSpec, aLocation, aType);
},
unregisterSelf: function(aCompMgr, aLocation, aType)
{
aCompMgr = aCompMgr.
QueryInterface(Components.interfaces.nsIComponentRegistrar);
aCompMgr.unregisterFactoryLocation(CLASS_ID, aLocation);
},
getClassObject: function(aCompMgr, aCID, aIID)
{
if (!aIID.equals(Components.interfaces.nsIFactory))
throw Components.results.NS_ERROR_NOT_IMPLEMENTED;
if (aCID.equals(CLASS_ID))
return HelloWorldFactory;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
canUnload: function(aCompMgr) { return true; }
};
/***********************************************************
module initialization
When the application registers the component, this function
is called.
***********************************************************/
function NSGetModule(aCompMgr, aFileSpec) { return HelloWorldModule; }
安装
针对扩展：
- 复制 HelloWorld.js 和 HelloWorld.xpt 到 {extensiondir}/components/。
- 从你的 profile 目录里删除 compreg.dat 和 xpti.dat。
- 重启应用程序。
针对 Firefox：
- 如果运行于源码，请复制 HelloWorld.js 和 HelloWorld.xpt 到 {objdir}/dist/bin/components 目录。
- 从 components 目录删除 compreg.dat 和 xpti.dat。
- 从 profile 目录删除 compreg.dat 和 xpti.dat。
- 重启应用程序。
使用你的组件
try {
// this is needed to generally allow usage of components in javascript
netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
var myComponent = Components.classes['@dietrich.ganx4.com/helloworld;1']
.createInstance(Components.interfaces.nsIHelloWorld);
alert(myComponent.hello());
} catch (anError) {
alert("ERROR: " + anError);
}
其它资源
- 两个来自 mozillazine 论坛的关于 implementing XPCOM components in JS 的话题，里面提供了一些解释、示例代码和除错贴士：
- Implementing XPCOM components in JavaScript 来自 kb.mozillazine.org
- Using XPCOM in JavaScript without leaking - 一篇必须阅读的文章。
- An example component
- Older JS+XPCOM notes - 包括一些 wrappedJSObject 信息。