Odoo 编辑器¶

Odoo 编辑器是 Odoo 自有的富文本编辑器。其源代码可在 html_editor 目录中找到。

Powerbox¶

Powerbox 是一个用户界面元素，其中包含命令，这些命令按类别组织。在编辑器中输入 / 时它就会出现。用户输入文本时可对命令进行筛选，并使用方向键导航。

修改 Powerbox¶

同一时间只应实例化一个 Powerbox，这项工作由编辑器自己完成。其 Powerbox 实例可在 powerbox 实例变量中找到。要更改 Powerbox 的内容和选项，请在编辑器实例化之前更改传给它的选项。

重要

切勿自行实例化 Powerbox。请始终使用当前编辑器自身的实例。

示例

假设我们想为 mass_mailing 模块在 Powerbox 中添加一个新命令 Document。我们希望将其添加到名为 Documentation 的新类别中，并让它位于 Powerbox 的最顶部。

mass_mailing 继承 web_editor 的 Wysiwyg 类，它在 start 方法中实例化编辑器。在此之前，它会调用自己的 _getPowerboxOptions 方法，可以很方便地重写该方法来添加我们的新命令。

既然 mass_mailing 已经重写了 _getPowerboxOptions，我们只需在其中添加新命令：

_getPowerboxOptions: function () {
    const options = this._super();
    // (existing code before the return statement)
    options.categories.push({
        name: _t('Documentation'),
        priority: 300,
    });
    options.commands.push({
        name: _t('Document'),
        category: _t('Documentation'),
        description: _t("Add this text to your mailing's documentation"),
        fontawesome: 'fa-book',
        priority: 1, // This is the only command in its category anyway.
    });
    return options;
}

重要

为了让命令和分类的名称与描述可以被翻译，请确保用 _t 函数将它们包裹起来。

小技巧

为避免优先级失控地攀升，不要为优先级使用随机数字：先查看已存在哪些其他优先级，再相应地选择你的值（就像处理 z-index 那样）。

打开自定义 Powerbox¶

可以使用自定义的分类和命令集打开 Powerbox，从而绕过所有已有的分类和命令。为此，请调用 Powerbox 的 open 方法，并把自定义的命令和分类传递给它。

示例

我们需要 Powerbox 的当前实例，它可以在当前编辑器中找到。在 Wysiwyg 类中，你会看到它是 this.odooEditor.powerbox。

现在用自定义“Documentation”分类中的自定义“Document”命令打开它：

this.odooEditor.powerbox.open(
    [{
        name: _t('Document'),
        category: _t('Documentation'),
        description: _t("Add this text to your mailing's documentation"),
        fontawesome: 'fa-book',
        priority: 1, // This is the only command in its category anyway.
    }],
    [{
        name: _t('Documentation'),
        priority: 300,
    }]
);

过滤命令¶

有三种过滤命令的方式：

通过 powerboxFilters Powerbox 选项。
通过给定命令的 isDisabled 条目。
用户只需在打开 Powerbox 后输入文本即可过滤命令。它会把该文本与分类和命令的名称进行模糊匹配。

开发手册¶

类别¶

名称	类型	说明
`name`	`string`	分类的名称
`priority`	`number`	用于对分类排序：优先级更高的分类在 Powerbox 中显示得更靠上（优先级相同的分类按字母顺序排列）

注解

如果存在多个同名分类，它们会被合并为一个。其优先级取自最后声明的那个分类版本中定义的值。

命令¶

名称	类型	说明
`name`	`string`	命令的名称
`category`	`string`	命令所属分类的名称
`description`	`string`	用于描述命令的简短文本
`fontawesome`	`string`	用作命令图标的 Font Awesome 名称
`priority`	`number`	用于对命令排序：优先级更高的命令在 Powerbox 中显示得更靠上（优先级相同的命令按字母顺序排列）
`callback`	`function` (`() => void`)	选中命令时要执行的函数（可以是异步的）
`isDisabled` （可选）	`function` (`() => void`)	用于在特定条件下禁用命令的函数（当它返回 `true` 时，命令将被禁用）

注解

如果命令指向尚不存在的分类，该分类将被创建并追加到 Powerbox 的末尾。

选项¶

以下选项可以传递给 OdooEditor，随后会被传递给 Powerbox 实例：

名称	类型	说明
`commands`	`array of commands`	要添加到编辑器默认命令中的命令
`categories`	`array of categories`	要添加到编辑器默认分类中的分类
`powerboxFilters`	`array of functions` (`commands => commands`)	用于过滤 Powerbox 中显示的命令的函数
`getContextFromParentRect`	`function` (`() => DOMRect`)	返回编辑器某个祖先元素的 `DOMRect` 的函数（当编辑器位于 iframe 中时可能有用）