🦉 应用（App）🦉

概述

每个 Owl 应用都有一个根组件、一组模板、一个环境（env），以及一些其他可能的配置项。App 类是一个简单的类，用来表示这些元素的集合。示例如下：

const { Component, App } = owl;

class MyComponent extends Component { ... }

const app = new App(MyComponent, { props: {...}, templates: "..." });
app.mount(document.body);

基本的流程是：使用根组件、模板和其他配置创建一个 App 实例，然后将该实例挂载到 DOM 中某个位置。

API

• constructor(Root[, config])：第一个参数是组件类（不是实例），第二个参数是可选的配置对象（详见下方）。

• mount(target, options)：第一个参数是 HTML 元素，第二个参数是可选的挂载选项对象（详见下方）。该方法将应用挂载到 DOM 中指定位置。注意：该方法是异步的，返回一个 Promise，在挂载完成后解析为组件实例。

  options 对象的可选字段如下：

  • position (string)：取值为 first-child 或 last-child，用于指定应用在目标节点中的插入位置。

• destroy()：销毁该应用实例。

配置项

config 对象可包含以下字段：

• env (object)：若提供，将作为应用中所有组件共享的环境对象。
• props (object)：传递给根组件的 props。
• dev (boolean, 默认=false)：若为 true，则应用在 开发模式（dev mode） 下运行。
• test (boolean, 默认=false)：与 dev 模式相同，但不会在控制台输出提示信息。
• translatableAttributes (string[])：需要被翻译的附加属性列表（参见 翻译）。
• translateFn (function)：用于翻译模板的函数（参见 翻译）。
• templates (string | xml document)：该应用中使用的所有模板。
• getTemplate ((s: string) => Element | Function | string | void)：当需要模板时，Owl 会调用该函数。如果返回 undefined，则会从 templates 中查找。
• warnIfNoStaticProps (boolean, 默认=false)：若为 true，当组件未定义 静态 props 描述 时会发出警告。
• customDirectives (object)：若提供，则用于处理模板中的自定义指令（即 t-custom-*，详见 自定义指令）。
• globalValues (object)：编译时可用的全局值对象。

mount 辅助方法

Owl 提供了一个 mount 辅助函数，可用一行代码完成挂载：

const { mount, Component } = owl;

class MyComponent extends Component {
    ...
}

mount(MyComponent, document.body, { props: {...}, templates: "..." });

该函数签名如下：

mount(Component, target, config)，参数说明：

• Component：组件类（作为应用根组件）。
• target：HTML 元素，组件将作为其最后一个子节点被挂载。
• config (可选)：配置对象（与 App 配置对象相同）。

通常情况下，使用 mount 更加方便。但如果需要访问应用实例本身，则可以直接使用 App 类。

多个根组件（Roots）

一个应用可以拥有多个“根”组件。在某些场景下（如 HTML 编辑器中动态插入内容），需要在 Owl 管理之外实例化子组件。

可以使用 createRoot 方法创建一个根组件，参数如下：

• Component：组件类（作为根组件）。
• config (可选)：配置对象，可以包含 props 或 env。

createRoot 返回一个对象，包含：

• mount(target) 方法：与 App.mount 相同。
• destroy() 方法：销毁该根组件。

const root = app.createRoot(MyComponent, { props: { someProps: true } });
await root.mount(targetElement);

// 稍后
root.destroy();

注意：与 Owl 的 App 类一样，调用方有责任在移除根组件前正确地销毁它，Owl 无法自动完成这一点。

加载模板

大多数应用在启动时都需要加载模板。实际示例如下：

// 主 JS 文件中：
const { loadFile, mount } = owl;

(async function setup() {
  const templates = await loadFile(`/some/endpoint/that/return/templates`);
  const env = {
    _t: someTranslateFn,
    templates,
    // 可能还有其他内容
  };

  mount(Root, document.body, { env });
})();

开发模式（Dev mode）

启用开发模式后，会激活一些额外的检查和开发功能：

• 启用 props 验证
• t-foreach 中会检查 key 是否唯一
• 生命周期钩子将被包装，以更易调试的方式报告错误
• 当 onWillStart 和 onWillUpdateProps 执行超过 3 秒时，控制台会发出警告，以帮助调试死锁问题