Skip to content

外部钩子(External hooks)#

外部钩子让你在 n8n 执行特定操作时运行自定义代码。使用它们来记录数据、更改数据，或通过抛出错误来禁止某个操作。

🌐 External hooks let you run custom code whenever n8n performs a specific operation. Use them to log data, change data, or forbid an action by throwing an error.

有两种类型：

🌐 There are two types:

  • 后端钩子：在服务器端运行，通过 EXTERNAL_HOOK_FILES 环境变量注册。
  • 前端钩子：在浏览器中运行，通过脚本标签加载。

有关用于注册钩子的环境变量，请参阅 外部钩子环境变量。

🌐 For the environment variables used to register hooks, refer to External hooks environment variables.

后端钩子(Backend hooks)#

可用钩子(Available hooks)#

| 钩子 | 参数 | 描述 |

| :------- | :---------| :---------- |

| credentials.create | [credentialData: ICredentialsDb] | 在创建新凭证之前调用。用于限制凭证的数量。 |

| credentials.delete | [id: credentialId] | 在凭证被删除之前调用。 |

| credentials.update | [credentialData: ICredentialsDb] | 在 n8n 保存现有凭据之前调用。 |

| frontend.settings | [frontendSettings: IN8nUISettings] | 在 n8n 启动时调用。例如，允许你覆盖前端数据，如显示的 OAuth URL。 |

| n8n.ready | [app: App] | n8n 准备好后调用一次。例如，可用于注册自定义 API 端点。 |

| n8n.stop | | 当 n8n 进程被停止时调用。允许你保存一些进程数据。 |

| oauth1.authenticate | [oAuthOptions: clientOAuth1.Options, oauthRequestData: {oauth_callback: string}] | 在 OAuth1 认证之前调用。用于覆盖 OAuth 回调 URL。 |

| oauth2.callback | [oAuth2Parameters: {clientId: string, clientSecret: string \| undefined, accessTokenUri: string, authorizationUri: string, redirectUri: string, scopes: string[]}] | 在 OAuth2 回调中调用。用于覆盖 OAuth 回调 URL。 |

| workflow.activate | [workflowData: IWorkflowDb] | 在工作流激活之前调用。用于限制活动工作流的数量。 |

| workflow.afterCreate | [workflowId: string] | 在工作流创建后调用。 |

| workflow.afterDelete | [workflowId: string] | 在工作流被删除后调用。 |

| workflow.afterUpdate | [workflowData: IWorkflowBase] | 在现有工作流保存后调用。 |

| workflow.create | [workflowData: IWorkflowBase] | 在创建工作流之前调用。用于限制已保存工作流的数量。 |

| workflow.delete | [workflowId: string] | 在工作流被删除之前调用。 |

| workflow.postExecute | [run: IRun, workflowData: IWorkflowBase] | 在工作流执行后调用。 |

| workflow.preExecute | [workflow: Workflow: mode: WorkflowExecuteMode] | 在工作流执行之前调用。允许你计算或限制工作流执行的次数。 |

| workflow.update | [workflowData: IWorkflowBase] | 在现有工作流被保存之前调用。 |

| workflow.afterArchive | [workflowId: string] | 在你归档工作流后调用。 |

| workflow.afterUnarchive | [workflowId: string] | 在你从归档恢复工作流后调用。 |

正在注册钩子(Registering hooks)#

通过注册包含钩子函数的钩子文件来设置钩子。要注册钩子，请设置环境变量 EXTERNAL_HOOK_FILES。

🌐 Set hooks by registering a hook file that contains the hook functions. To register a hook, set the environment variable EXTERNAL_HOOK_FILES.

你可以将变量设置为单个文件：

🌐 You can set the variable to a single file:

EXTERNAL_HOOK_FILES=/data/hook.js

或者，包含多个以冒号分隔的文件：

🌐 Or to contain multiple files separated by a colon:

EXTERNAL_HOOK_FILES=/data/hook1.js:/data/hook2.js

钩子文件(Hook files)#

钩子文件是常规的 JavaScript 文件，格式如下：

🌐 Hook files are regular JavaScript files that have the following format:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
module.exports = {
    "frontend": {
        "settings": [
            async function (settings) {
                settings.oauthCallbackUrls.oauth1 = 'https://n8n.example.com/oauth1/callback';
                settings.oauthCallbackUrls.oauth2 = 'https://n8n.example.com/oauth2/callback';
            }
        ]
    },
    "workflow": {
        "activate": [
            async function (workflowData) {
                const activeWorkflows = await this.dbCollections.Workflow.count({ active: true });

                if (activeWorkflows > 1) {
                    throw new Error(
                        'Active workflow limit reached.'
                    );
                }
            }
        ]
    }
}

钩子函数(Hook functions)#

钩子或钩子文件可以包含多个钩子函数，所有函数按顺序执行。

🌐 A hook or a hook file can contain multiple hook functions, with all functions executed one after another.

如果钩子函数的参数是对象，则可以更改该参数的数据来更改 n8n 的行为。

🌐 If the parameters of the hook function are objects, it's possible to change the data of that parameter to change the behavior of n8n.

你也可以在任何钩子函数中使用 this.dbCollections 访问数据库（参考上面 Hook files 中的代码示例）。

🌐 You can also access the database in any hook function using this.dbCollections (refer to the code sample in Hook files above).

前端外部钩子(Frontend external hooks)#

就像后端的外部钩子一样，也可以在前端代码中定义外部钩子，每当用户执行特定操作时，n8n 都会执行这些钩子。例如，你可以使用它们来记录数据和修改数据。

🌐 Like backend external hooks, it's possible to define external hooks in the frontend code that get executed by n8n whenever a user performs a specific operation. You can use them, for example, to log data and change data.

可用钩子(Available hooks)#

| 钩子 | 描述 |

| :------- | :---------- |

| credentialsEdit.credentialTypeChanged | 当现有凭据的类型发生变化时调用。 |

| credentials.create | 当有人创建新凭证时调用。 |

| credentialsList.dialogVisibleChanged | |

| dataDisplay.nodeTypeChanged | |

| dataDisplay.onDocumentationUrlClick | 当有人选择帮助文档链接时调用。 |

| execution.open | 当已有执行被打开时调用。 |

| executionsList.openDialog | 当有人从现有的工作流执行中选择一个执行时调用。 |

| expressionEdit.itemSelected | |

| expressionEdit.dialogVisibleChanged | |

| nodeCreateList.filteredNodeTypesComputed | |

| nodeCreateList.nodeFilterChanged | 当有人对节点面板过滤器进行任何更改时调用。 |

| nodeCreateList.selectedTypeChanged | |

| nodeCreateList.mounted | |

| nodeCreateList.destroyed | |

| nodeSettings.credentialSelected | |

| nodeSettings.valueChanged | |

| nodeView.createNodeActiveChanged | |

| nodeView.addNodeButton | |

| nodeView.mount | |

| pushConnection.executionFinished | |

| showMessage.showError | |

| runData.displayModeChanged | |

| workflow.activeChange | |

| workflow.activeChangeCurrent | |

| workflow.afterUpdate | 当有人更新现有工作流时调用。 |

| workflow.open | |

| workflowRun.runError | |

| workflowRun.runWorkflow | 当工作流执行时调用。 |

| workflowSettings.dialogVisibleChanged | |

| workflowSettings.saveSettings | 当有人保存工作流设置时调用。 |

注册前端钩子(Registering frontend hooks)#

你可以通过在页面上加载 hooks 脚本来设置 hooks。其中一种方法是在项目中创建一个 hooks 文件，并在你的 editor-ui/public/index.html 文件中添加一个 script 标签：

🌐 You can set hooks by loading the hooks script on the page. One way to do this is by creating a hooks file in the project and adding a script tag in your editor-ui/public/index.html file:

1
<script src="frontend-hooks.js"></script>

前端钩子文件(Frontend hook files)#

前端外部钩子文件是常规的 JavaScript 文件，格式如下：

🌐 Frontend external hook files are regular JavaScript files which have the following format:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
window.n8nExternalHooks = {
  nodeView: {
    mount: [
      function (store, meta) {
        // do something
      },
    ],
    createNodeActiveChanged: [
      function (store, meta) {
        // do something
      },
      function (store, meta) {
        // do something else
      },
    ],
    addNodeButton: [
      function (store, meta) {
        // do something
      },
    ],
  },
};

前端钩子函数(Frontend hook functions)#

你可以为每个钩子定义多个钩子函数。n8n 会使用以下参数调用每个钩子函数：

🌐 You can define multiple hook functions per hook. n8n calls each hook function with the following arguments:

  • store：Vuex 存储对象。你可以用它来更改或获取存储中的数据。
  • metadata：包含钩子提供的任何数据的对象。要查看传递了什么，请在 editor-ui 包中搜索该钩子。