注册 PlaceholderAPI 占位符¶

警告

占位符管理器是一个可选管理器。只有在启用 PySpigot 插件时服务器上存在 PlaceholderAPI 插件时，才能访问此管理器。

PySpigot 包含一个管理器，可与 PlaceholderAPI 交互，如果您想在脚本中注册占位符扩展。

有关将占位符管理器导入到您的脚本中的说明，请访问通用信息页面。

占位符管理器使用¶

所有由脚本创建的占位符都将遵循此一般格式：%script:<scriptname>_<placeholder>%，其中 <scriptname> 是您脚本的名称（不带 .py），<placeholder> 是特定的占位符，您需要在占位符的 "替换器" 函数中自行处理。有关详细信息，请参阅下面的代码示例。

关系型占位符也可以通过占位符管理器注册，并遵循一般格式%rel_script:<scriptname>_<placeholder>%，其中 <scriptname> 是您的脚本的名称（不带 .py），<placeholder> 是特定的占位符，您需要在关系型占位符的 "替换器" 函数中自行处理。有关详细信息，请参阅下面的代码示例。

占位符管理器提供了几个函数，用于注册/注销占位符处理:

registerPlaceholder(placeholder_function): 注册一个新的占位符扩展，默认作者为("脚本作者")和版本为("1.0.0")。
- 当占位符被使用时，将调用 placeholder_function。应返回应替换占位符的文本。
- 返回一个ScriptPlaceholder，代表被注册的占位符。
registerPlaceholder(placeholder_function, relational_placeholder_function): 注册一个新的占位符扩展，默认作者为("脚本作者")和版本为("1.0.0")。
- 当占位符被使用时，将调用 placeholder_function。应返回应替换占位符的文本。此参数可以是None。
- 当使用关联占位符时，将使用relational_placeholder_function。应返回应替换占位符的文本。此参数可以是None。
- 返回一个ScriptPlaceholder，代表被注册的占位符。
registerPlaceholder(placeholder_function, author, version): 注册一个新的占位符扩展，自定义作者和版本。
- 当占位符被使用时，将调用 placeholder_function。应返回应替换占位符的文本。
- 返回一个ScriptPlaceholder，代表被注册的占位符。
registerPlaceholder(placeholder_function, relational_placeholder_function, author, version): 注册一个新的占位符扩展，自定义作者和版本。
- 当占位符被使用时，将调用 placeholder_function。应返回应替换占位符的文本。
- 当使用关联占位符时，将使用relational_placeholder_function。应返回应替换占位符的文本。此参数可以是None。
- 返回一个ScriptPlaceholder，代表被注册的占位符。
unregisterPlaceholder(placeholder): 注销先前注册的占位符。接受之前由registerPlaceholder函数返回的ScriptPlaceholder。

提示

你不需要在脚本停止或卸载时取消注册占位符。PySpigot会为你处理这些事务。

注意

脚本一次只能注册一个占位符扩展。要了解如何为脚本定义多个占位符，请查看下面的代码示例。

代码示例¶

常规占位符¶

让我们看一下以下代码，定义并注册了一个占位符扩展，并替换了两个占位符：

import pyspigot as ps # (1)!

def replace(offline_player, placeholder): # (2)!
    if placeholder == 'placeholder1': # (3)!
        return '替换占位符1！'
    elif placeholder == 'placeholder2': # (4)!
        return '替换占位符2！'

placeholder = ps.placeholder.registerPlaceholder(replace, None) # (5)!

在这里，我们导入PySpigot并命名为ps，以便使用占位符管理器（placeholder）。
在这里，我们定义replace，一个在使用占位符时将被调用的函数。此函数接受两个参数。offline_player是一个代表与占位符相关联的玩家的Bukkit API OfflinePlayer。placeholder是特定占位符的文本。
在这里，我们检查placeholder是否等于特定占位符placeholder1，我们定义的一个占位符。如果placeholder等于placeholder1，则返回“被替换”的文本。
在这里，我们使用elif检查placeholder是否等于另一个特定占位符placeholder2，另一个我们定义的占位符。如果placeholder等于placeholder2，则返回“被替换”的文本。
在这里，我们使用 registerPlaceholder 函数注册了我们的占位符扩展，并传入了之前定义的替换函数。我们还将 registerPlaceholder 的返回值分配给 placeholder。这是一个 ScriptPlaceholder 对象，代表了注册的占位符扩展。如果将来想要取消注册占位符扩展，可以使用此对象。在这个示例中，我们还将第二个参数传递为 None，因为第二个参数应为一个用于替换关系占位符的函数，而在本示例中我们没有这个需求。

请注意，占位符扩展的替换函数需要接受两个参数：

offline_player 参数是与占位符相关联的玩家。例如，如果占位符在命令上下文中使用，则 offline_player 将是输入/执行命令的玩家。如果在使用占位符时未关联玩家，则此参数将为 None。
placeholder 参数是使用的占位符的名称。

所有占位符扩展函数都应遵循此语法。

警告

在上面的示例中，以及所有占位符中，如果占位符未关联玩家，则 offline_player 可能为 None。

如果脚本的名称是 test.py，上面示例中的占位符分别为 %script:test_placeholder1% 和 %script:test_placeholder2%。

关系占位符¶

让我们看下面的代码，该代码定义并注册了一个关系占位符的占位符扩展。

import pyspigot as ps # (1)!

def replace_relational(player_one, player_two, placeholder): # (2)!
    if placeholder == 'player_distance': # (3)!
        return str(player_one.getLocation().distance(player_two.getLocation())) # (4)!

placeholder = ps.placeholder.registerPlaceholder(None, replace_relational) # (5)!

在这里，我们导入 PySpigot 作为 ps 来利用占位符管理器 (placeholder)。
在这里，我们定义了 replace_relational 函数，当使用关系占位符时将被调用。这个函数接受三个参数。 player_one 是与关系占位符相关的第一个玩家，player_two 是与其相关的第二个玩家。placeholder 是特定关系占位符的文本。
在这里，我们检查 placeholder 是否等于特定的关系占位符，在这种情况下是 player_distance。
在这里，我们返回从玩家一到玩家二的距离，用于替换文本。
在这里，我们使用 registerPlaceholder 函数注册了我们的占位符扩展，传递了之前定义的替换函数。我们还将 registerPlaceholder 的返回值赋给了 placeholder。这是一个 ScriptPlaceholder 对象，表示已注册的占位符扩展。如果需要，在以后可以用它来取消注册占位符扩展。我们还将此函数的第一个参数传递为 None，因为第一个参数接受一个函数用于替换常规占位符，而在此示例中我们没有这样做。

如果脚本的名称是 test.py，上面示例中的占位符将是 %rel_script:test_player_distance%。

提示

```markdown
多个关联占位符可以同时注册（使用相同的替换函数），按照上一节示例的结构进行操作。

### 取消占位符

继续上面的代码示例：

``` py linenums="1"
ps.placeholder.unregisterPlaceholder(placeholder) # (1)!

在这里，我们通过传递我们在注册占位符时分配的ScriptPlaceholder对象来注销占位符的扩展。

多个占位符¶

正如您在上面的示例中所看到的，您无需为要定义的每个特定占位符注册新的占位符扩展。相反，您只需检查您替换函数的placeholder参数是否等于您希望使用if和elif来定义的占位符。

总结¶

脚本定义的占位符遵循格式 %script:<scriptname>_<placeholder>%。
关联占位符遵循格式 %rel_script:<scriptname>_<placeholder>%。
普通占位符替换函数应该接受两个参数，offline_player 和 placeholder。你可以随意命名它们。当占位符被使用时将会被调用。offline_player 是与占位符关联的玩家，如果有的话。placeholder 是被使用的具体占位符。
关联占位符替换函数应该接受三个参数，player_one、player_two 和 placeholder。你可以随意命名它们。当占位符被使用时将会被调用。player_one 和 player_two 是与关联占位符相关联的两个玩家。placeholder 是被使用的具体占位符。
使用 registerPlaceholder(placeholder_function, relational_placeholder_function) 或 registerPlaceholder(placeholder_function, relational_placeholder_function, author, version) 将你的占位符注册到 PySpigot 的占位符管理器。
每个脚本一次只能注册一个占位符扩展。通过检查你的替换函数的 placeholder 参数（使用 if 和 elif）来处理多个占位符。
在注册占位符扩展时，所有注册函数都会返回一个 ScriptPlaceholder，以便以后可以用于取消注册占位符扩展。