Q100385：如何使用 Python 在 Katana 中注册回调和事件处理程序，以便根据用户操作添加自定义功能

Elisabeth Wetchy

更新: 2026年05月12日 22:45

创建: 2018年02月20日 15:34

概括

本文解释了如何在Katana中注册回调或事件处理程序，并详细介绍了在哪里可以找到有关可用回调和事件类型以及其回调函数的预期输入参数的信息。
回调和事件的相关文档也可以在Katana开发者指南中找到。以下文章提供了一些关于如何实现它们的实用示例。

更多信息

回调函数是添加到Katana环境中的一段 Python 代码，当Katana中发生各种事件（例如创建节点或加载脚本）时，该代码会自动运行。

事件是指由用户操作或其他来源（例如鼠标点击或按键）引起的动作。事件处理程序是用于处理事件的例程，允许程序员编写在事件发生时执行的代码。

在某些情况下（例如在保存文件之前）， Katana会触发回调，调用代码会等待回调执行完毕后再继续，从而允许用户在保存项目之前对其进行修改。

相反， Katana的事件系统会将事件排队，并在“稍后”处理。这意味着回调会更及时，但通常也应该非常快，否则可能会导致 UI 在执行过程中卡顿。

回调函数和事件处理程序在很多情况下都很有用，例如在创建新的Katana项目时更改项目设置，或者对某些节点参数的值更改做出反应。

回调函数

在Katana中，针对不同的情况可以使用回调函数，例如软件启动、 Katana项目加载或节点创建。要查看所有可用回调函数的完整列表，请在 Python 选项卡中运行以下代码：

from Katana import Callbacks
print(dir(Callbacks.Type))

要了解哪些关键字参数传递给了每种回调类型，您可以注册以下回调函数，该回调函数在被调用时会打印出输入参数：

def Hello(**kwargs):
    for i in kwargs.keys():
        print(i)

from Katana import Callbacks
Callbacks.addCallback(Callbacks.Type.onSceneLoad, Hello)

这些参数可以在回调函数中访问，例如：

def Hello(**kwargs):
   print(kwargs.get('filename'))

from Katana import Callbacks
Callbacks.addCallback(Callbacks.Type.onSceneLoad, Hello)

事件处理程序

Katana中有许多不同的事件类型可供已注册的处理程序监听。要查看所有可用事件类型的列表，请在 Python 选项卡中运行以下命令：

 from Katana import Utils
print ( sorted ( Utils . EventModule . GetAllRegisteredEventTypes ()))

要查找每种事件类型对应的输入参数，您可以为特定事件注册以下处理程序。事件触发时，该处理程序会打印出参数。以下示例打印了“node_create”事件类型的输入参数：

def node_CreateCallback(eventType, eventID, **kwargs):
    for i in kwargs.keys():
        print(i)

Utils.EventModule.RegisterEventHandler(node_CreateCallback, 'node_create')

一旦知道了输入参数，就可以在事件处理函数中使用它们。以下是一个示例事件处理程序，可以注册该程序来监听用户首选项的更改，并打印出首选项的名称及其新值：

def PrefChangedCallback(eventType, eventID, prefKey, prefValue):
    print(prefKey, "preference changed to:", prefValue)

Utils.EventModule.RegisterEventHandler(PrefChangedCallback, 'pref_changed')

节点参数更改事件处理程序

例如，如果一个事件处理函数只需要响应特定节点参数的变化，则可以将其注册为监听parameter_finalizeValue事件。可以在处理函数内部检查已更改参数的名称，以确定它是否是相关的参数：

def myParamCallback(eventType, eventID, node, param):
    if (node.getName() == "CameraCreate") and (param.getName() == 'fov'):
        print("FOV for the following camera changed to " + repr(param.getValue(0)) + ": " + node.getParameter('name').getValue(0))

Utils.EventModule.RegisterEventHandler(myParamCallback, "parameter_finalizeValue")

事件处理程序不一定会在事件排队后立即执行。如果某些代码依赖于特定事件的处理和事件处理程序的执行，则可能需要调用以下方法：

Utils.EventModule.ProcessAllEvents()

有关回调和事件处理程序的更多信息，请参阅我们的Katana开发人员指南中的“回调和事件”部分。

在Katana启动时注册回调或事件处理程序

Katana启动时可以按如下方式自动注册回调函数或事件处理程序：

在单个 Python 函数中定义回调函数或事件处理函数要执行的所有操作，并按照以下示例代码所示注册该函数：

from Katana import Utils, Callbacks

def PrefChangedCallback(eventType, eventID, prefKey, prefValue):
    print(prefKey, "preference changed to:", prefValue)

Utils.EventModule.RegisterEventHandler(PrefChangedCallback, 'pref_changed')

def Hello(**kwargs):
    print(kwargs.get('filename'))

Callbacks.addCallback(Callbacks.Type.onSceneLoad, Hello)

将此内容复制粘贴到文本编辑器中，然后保存文件。
将文件重命名为 init.py，并确保文件浏览器中显示文件扩展名，这是为了验证文件扩展名是 .py 而不是 .txt 或其他类型。
将文件放置在 .katana 文件夹中，或者放置在$KATANA_RESOURCES环境变量中定义的路径下的Startup文件夹中。

有关KATANA _RESOURCES的更多信息，请参阅Katana安装指南中的相应主题。

下次启动Katana时，当指定操作发生时，回调函数将被执行；当相关事件被排队并处理时，事件处理函数将被执行。在上面的示例中，当更改首选项或加载Katana项目时，新的首选项值或项目文件路径将分别输出到终端。

概括

更多信息

更多帮助