插件

插件 可以让您使用 Python 扩展 Blender 的功能。大多数情况下，您可以从扩展系统中获取插件。

Tip

如果启用后插件功能未激活，请打开控制台窗口，检查是否有错误发生。

互联网访问

如果插件需要使用互联网，则必须检查（只读）属性 bpy.app.online_access．该选项由偏好设置控制，可以通过命令行（--offline-mode / --online-mode）进行覆写。

若需更完善的错误信息，您还可检查 bpy.app.online_access_override，以确定用户是否能在偏好设置中启用允许联机访问。

Note

遵循此设置的插件只有在启用的情况下才会连接到互联网。然而，Blender 无法阻止第三方插件违反这一规则。

打包依赖

若要将插件作为扩展捆绑，必须确保其具备独立性。这意味着它们必须包含所有相关依赖项。特别是第三方 Python 模块。

为此，有几种选择：

与 Python Wheel 捆绑。

这是捆绑依赖项的推荐方式。

将其他插件捆绑在一起。

如果一个插件依赖于另一个插件，建议使用此方法。

确保单独及组合的插件均检查已注册类型（操作符、面板等）。若插件以捆绑包形式及单独安装，则可避免界面中操作符与面板的重复配置。

与 Vendorize 捆绑

该方法可将纯 Python 依赖项打包为子模块。

这种方法的优势在于可避免版本冲突，但需要对每个包进行配置设置。

本地存储

插件不得默认其目录具有用户可写权限，因为 “系统” 存储库可能不具备此特性。将文件写入插件目录还存在一个缺点：升级扩展时会删除所有文件。

需要独立用户目录的插件应使用为此目的提供的实用功能：

extension_directory = bpy.utils.extension_path_user(__package__, path="", create=True)

如需创建子目录，可通过 path 参数实现。

该目录将在系统升级期间保留，但若卸载扩展则会被删除。

旧式 vs 扩展插件

随着 Blender 4.2 中扩展功能的引入，创建插件的旧方法被认为已经过时。虽然变化不大，但对现有插件的影响却很大。

为了实现平稳过渡，Blender 将继续支持所谓的旧式插件。它们可以通过用户偏好设置中的安装旧式插件按钮安装。

我们敦促所有插件维护者转换他们想要分享的插件，以便它们能够适应未来的需要，并支持从扩展平台更新等功能。

将一个旧式插件转换为扩展

  1. 创建一个清单文件。

  2. 删除 bl_info 信息（该信息现在在清单中）。

  3. 将所有对模块名称的引用替换为 __package__．

  4. 让所有模块导入都使用相对导入。

  5. 使用 wheels 打包您的外部 Python 依赖项。

  6. 记住要进行彻底的测试。

Note

对于测试，重要的是从磁盘安装扩展并检查是否一切正常。这将使您尽可能接近最终体验。

扩展与命名空间

旧式插件会通过其模块名称来访问偏好设置。当安装来自不同存储库的同名扩展时，可能导致名称冲突。为避免此类冲突，存储库名称现已被纳入命名空间。

例如，现在模块名将不再是 kitsu，而是 bl_ext.{repository_module_name}.kitsu．

这对偏好设置和模块导入会有一些影响。

用户设置与 __package__

插件可自定义偏好设置，其标识符采用包名称。可通过 __package__ 访问。

这一机制在原有插件中已得到支持，但未得到强化。因此，这可能破坏向后兼容性。

以前：

class KitsuPreferences(bpy.types.AddonPreferences):
    bl_idname = "kitsu"
    # ... snip ...

# Access with:
addon_prefs = bpy.context.preferences.addons["kitsu"]

现在：

class KitsuPreferences(bpy.types.AddonPreferences):
    bl_idname = __package__
    # ... snip ...

# Access with:
addon_prefs = bpy.context.preferences.addons[__package__]
子包

定义子包（带有独立 __init__.py 文件的子目录）的扩展若需使用此标识符，必须通过相对导入方式引入顶层级包。

from .. import __package__ as base_package

此时可以使用 base_package 代替 __package__．使用 .. 表示相对于该包的父级包进行导入，子子包则必须使用 ...，以此类推。

Note

  • __package__ 的值在不同系统间存在差异，因此切勿用字面字符串进行替换。

  • 扩展不得修改 __package__ 的值，否则可能导致系统异常运行或错误发生。

相对导入

以前:

from kitsu import utils

现在:

from . import utils

在插件模块中导入包时，需使用相对路径。这是 Python 的标准功能，仅适用于包含多个文件夹的插件。

这一机制在原有插件中已得到支持，但未得到强化。因此，这可能破坏向后兼容性。