GJS中GIRepository如何确定typelib对应导入标识及相关问题

1. typelib 导入标识符规则与普通模块搜索逻辑 #

typelib 正确导入名的确定方法 #

typelib导入名和文件名不匹配的核心规则是：typelib的导入标识符取的是文件内部记录的GObject命名空间名，和文件名没有强制对应关系，且导入时不需要写版本后缀。

• 你测试的WebKit2-4.0.typelib文件名中，WebKit2是命名空间名，4.0是该typelib的版本号，GJS导入时会自动在搜索路径下匹配对应命名空间的最高兼容版本，不需要手动把版本号写到导入语句里，因此imports.gi["WebKit2-4.0"]的写法本身不符合规则。
• imports.gi.WebKit无法工作是因为当前搜索路径下根本没有命名空间为WebKit的typelib，你安装的WebKit2相关typelib的命名空间就是WebKit2，不存在省略数字2的别名。

不需要靠猜测确定导入名，两种方法可以直接拿到本地所有合法的typelib导入标识符：

1. 终端执行命令直接枚举本地所有可用typelib的命名空间：

   ls /lib/x86_64-linux-gnu/girepository-1.0/*.typelib | xargs -n1 basename | sed 's/-[0-9.]*\.typelib$//' | sort -u
   

2. 用GJS内建的GIRepository API查询所有可加载的命名空间：

   const GIRepository = imports.gi.GIRepository;
   const repo = GIRepository.Repository.get_default();
   // 扫描所有搜索路径预加载可用typelib
   repo.get_search_path().forEach(path => {
       try { repo.require_private(null, path, 0); } catch(e) {}
   });
   // 打印的结果就是所有合法的 imports.gi.xxx 标识符
   log(repo.get_loaded_namespaces());
   

非gi模块的搜索逻辑 #

你的理解完全正确：imports.gi是GJS内置的特殊模块入口，专门处理GObject Introspection绑定的加载，除此之外的所有普通JavaScript模块导入，都会严格按照imports.searchPath数组中存储的目录顺序，逐层匹配对应路径的.js文件。比如写imports.ui.main时，GJS会依次遍历searchPath下的每个目录，查找ui/main.js文件，找到第一个匹配项就加载，全部路径都找不到时直接抛出导入错误。

2. API 调用异常问题与实用参考资料 #

官方文档函数无法调用的常见原因 #

官方文档记载的函数无法调用基本是三类原因：

• 对应API在gir注解中标记了(introspectable=0)或(skip)，这类API本身因为内存管理逻辑特殊、参数类型不支持绑定等原因，根本不会生成JS侧的绑定方法，文档如果没有做过滤就会展示出来，自然无法调用。
• 版本不匹配：本地安装的typelib版本和文档参考的版本不一致，对应API可能还未合入，或者已经被废弃、移除。
• 调用方式错误：GObject体系下大量方法是实例方法，必须拿到对应类型的实例才能调用，直接在类/命名空间上调用自然会报错。

带示例的高可靠性参考资料 #

不需要找零散的第三方资料，以下几个渠道的内容准确性远高于通用API文档，且附带大量可运行示例：

• 本地gir文件：所有typelib对应的源gir文件一般存储在/usr/share/gir-1.0/目录下，是XML格式的纯文本，里面明确标注了每个可绑定API的参数、返回值、调用规则，不可绑定的API也会有明确注解，是最准确的一手参考。
• GJS官方使用指南：和GJS稳定版完全对齐，覆盖GTK、Gio、WebKit等常用库的基础使用场景，每个知识点都附带可直接运行的示例代码。
• GNOME原生应用源码：GNOME桌面环境下大量核心应用（比如文件管理器、设置面板、终端）都是用GJS开发的，所有API调用都是经过生产验证的正确写法，碰到拿不准的用法直接搜对应源码的调用逻辑即可。
• GJS自带测试用例：GJS安装目录下的测试文件夹里覆盖了绝大多数绑定API的调用示例，参数传法、返回值处理逻辑都有现成的参考。

内容的提问来源于stack exchange，提问作者Schmaehgrunza