基本配置

对话框配置包含三个主要部分，以对应对话框 UI 的三个主要部分。

1. 标题

   • 对话框的标题。

   • 显示在对话框的头部。

2. 主体

   • 对话框的主体。

   • 主体组件可以是面板或标签面板，其中可以包含一系列面板组件，如按钮、输入框和文本。

3. 按钮

   • 一组页脚按钮，显示在对话框的页脚。

基本示例

显示 HTML 信息的基本对话框的配置可能如下所示：

tinymce.activeEditor.windowManager.open({
  title: 'Dialog Title', // 对话框的标题 - 显示在对话框头部
  body: {
    type: 'panel', // 根主体类型 - Panel 或 TabPanel
    items: [ // 面板组件列表
      {
        type: 'htmlpanel', // 一个 HTML 面板组件
        html: 'Panel content goes here.'
      }
    ]
  },
  buttons: [ // 页脚按钮列表
    {
      type: 'submit',
      text: 'OK'
    }
  ]
});

选项

有关传递给某些配置选项的 dialogApi 对象的更多信息，请参阅对话框实例 API文档。

事件回调函数

每个事件回调函数 - onAction、onSubmit、onCancel、onChange、onClose 和 onTabChange - 在所有可能触发它们的对话框组件之间共享。例如，自定义类型的页脚按钮和对话框面板按钮都会触发 onAction。因此，可能由多个组件触发的回调函数会传入一个对象（在上面称为 details），其中包含触发事件的组件的 name。

任何未传递 details 对象的回调函数都假定对话框仅包含一个可触发该函数的组件，或者假定函数由多个组件触发也无关紧要。例如，onSubmit 仅在用户点击 Submit 类型的页脚按钮时触发，且 TinyMCE 假定对话框仅包含一个 Submit 类型的按钮。相比之下，onCancel 和 onClose 均可通过点击对话框右上角的 X 按钮或点击 Cancel 类型的页脚按钮触发。这两个按钮功能相同，因此 TinyMCE 不对它们进行区分。

配置参数

align

align 是一个可选项，可添加到对话框标签以设置标签文本的对齐方式。

该属性的默认值为 start。

如果未显式设置该属性，也将应用此值。

类型：String

默认值：start

可能值：'+start+'、'+center+'、'+end+'

值 start 和 end 指文本行的开头或结尾，且相对于显示语言而言。

对于从左到右书写的语言（例如英语或越南语），start 将对话框标签设置为左对齐，end 将对话框标签设置为右对齐。

对于从右到左书写的语言（例如阿拉伯语或波斯语），start 将对话框标签设置为右对齐，end 将对话框标签设置为左对齐。

示例：使用 align 将对话框标题设置为 end-aligned（末端对齐）

tinymce.activeEditor.windowManager.open({
  title: 'Dialog Title', // The dialog's title - displayed in the dialog header
  body: {
    type: 'panel', // The root body type - a Panel or TabPanel
    items: [
      {
        type: 'label', // component type
        label: 'Caption', // text for the group label
        align: 'end',
        items: [
          {
            type: 'htmlpanel', // an HTML panel component
            html: 'Panel content goes here.'
          }
        ]
      }
    ]
  },
  buttons: [ // A list of footer buttons
    {
      type: 'submit',
      text: 'OK'
    }
  ]
});

border

border 是一个可选项，可用于添加到 iframe 对话框组件。

该属性的默认值为 false。

当该属性设置为 true 时，iframe 组件周围会显示边框。

当 iframe 组件获得焦点时（例如，使用 Tab 键在活动对话框中切换焦点），边框也会高亮显示。

类型：Boolean

默认值：false

可能值：true、false

示例：使用 border 在 iframe 组件周围显示边框

tinymce.activeEditor.windowManager.open({
  title: 'Dialog Title', // The dialog's title - displayed in the dialog header
  body: {
    type: 'panel', // The root body type - a Panel or TabPanel
    items: [ // A list of panel components
      {
        name: 'preview',
        type: 'iframe',
        border: true,
      }
    ]
  },
  buttons: [ // A list of footer buttons
    {
      type: 'submit',
      text: 'OK'
    }
  ]
});

使用 buttons 配置无页脚的对话框

除了常规功能外，buttons 属性还可用于阻止页脚部分的显示。

要配置自定义对话框使其在显示时不渲染页脚部分，可将 buttons 属性设置为空数组 []，或完全省略该属性。

一个没有按钮或页脚的对话框的基本示例

tinymce.activeEditor.windowManager.open({
  title: 'Dialog Title', // The dialog's title - displayed in the dialog header
  body: {
    type: 'panel', // The root body type - a Panel or TabPanel
    items: [ // A list of panel components
      {
        type: 'htmlpanel', // an HTML panel component
        html: 'Panel content goes here.'
      }
    ]
  },
  buttons: []
});

persistent

当 persistent 属性设置为 true 时，内联对话框可在失去焦点后保持打开状态。

如果最终用户将焦点赋予 TinyMCE 编辑器的其他部分（例如文档编辑器或菜单），内联对话框将保持打开状态。

将该属性设置为 true 不会覆盖关闭对话框的常规机制，例如点击 Close 按钮或按下 Esc 键。

该属性的默认值为 false。

如果内联对话框处于打开状态，且焦点完全从 TinyMCE 编辑器移开（例如，最终用户将焦点切换到可用的主机浏览器 UI 元素），无论 persistent 属性的值如何，打开的内联对话框都将保持打开状态。这是在此属性可用之前就存在的行为，并继续保留。

类型：Boolean

默认值：false

可能值：true、false

示例：使用 persistent

tinymce.activeEditor.windowManager.open({
  title: '对话框标题', // 对话框标题 - 显示在对话框头部
  body: {
    type: 'panel', // 根 body 类型 - Panel 或 TabPanel
    items: [ // 面板组件列表
      {
        type: 'htmlpanel', // HTML 面板组件
        html: '面板内容放在这里。'
      }
    ]
  },
  buttons: [ // 底部按钮列表
    {
      type: 'submit',
      text: '确定'
    }
  ]},
  { inline: 'toolbar', persistent: true }
});

示例：使用 focus 重新聚焦已打开但失去焦点的对话框

由于具有 { persistent: true } 属性的对话框在失去焦点时不会关闭，最终用户有可能再次打开同一个对话框的实例。

为了防止这种情况

• 添加检查以确认对话框是否已经打开；并且

• 使用 DialogInstanceAPI 中的 focus 方法将焦点转移到已打开的对话框，而不是创建新对话框实例。

let dialogOpened = false;
let dialogInstanceApi = null;

const openDialog = () => {
  dialogOpened = true;
  dialogInstanceApi = editor.windowManager.open({
    title: '测试',
    body: {
      type: 'panel',
      items: [{
        type: 'bar',
        items: [{
            type: 'input',
            name: 'name',
            placeholder: '名称',
            maximized: true
          }
        ]
      }]
    },
    onClose: () => {
      dialogOpened = false;
    },
    buttons: [{
      type: 'cancel',
      name: 'cancel',
      text: '取消'
    }],
    initialData: {
      name: ''
    }
  }, {
    inline: 'bottom',
    persistent: true
  });
};

const focusDialog = () => {
  dialogInstanceApi.focus('name');
}

editor.ui.registry.addButton('example', {
  type: 'button',
  text: '示例',
  tooltip: '示例',
  onAction: () => {
    dialogOpened ? focusDialog() : openDialog();
  }
});

streamContent

streamContent 是一个可选属性，可用于添加至 iframe 对话框组件。

该属性的默认值为 false。

当 streamContent 设置为 true 时，将使用 document.write() 方法更新 iframe 对话框组件中的内容，而不是通过设置 srcdoc 属性。

设置 srcdoc 属性会导致 iframe 重新加载。这会在大多数现代浏览器中产生视觉上不和谐的闪烁效果，尤其是当内容快速更新时。

此外，通过 srcdoc 属性执行更新意味着 iframe 的内容不可访问。因此，在内容更新时无法自动将 iframe 的内容滚动到底部。

将 streamContent 设置为 true 可最小化闪烁效果。

如果 iframe 组件已滚动至末尾，streamContent: true 也会将视图保持在当前位置。用户体验类似于向 iframe 组件快速键入内容。

但是，用户仍可以在内容更新时滚动浏览 iframe 组件。如果在更新过程中将视图滚动回末尾，streamContent: true 设置将再次保持视图位置。

类型： Boolean

默认值： false

可能的值： true false

示例：设置 iframe 组件使用 streamContent 属性显示更新中的内容

tinymce.activeEditor.windowManager.open({
  title: '对话框标题', // 对话框标题 - 显示在对话框头部
  size: 'normal',
  body: {
    type: 'panel', // 根 body 类型 - Panel 或 TabPanel
    items: [ // 面板组件列表
      {
        name: 'preview',
        type: 'iframe',
        streamContent: true
      }
    ]
    },
    buttons: [ // 底部按钮列表
      {
        type: 'submit',
        text: '确定'
      }
    ]
}, { inline: 'bottom' } );

对话框位置

上述示例还为对话框添加了第二个参数 — `{ inline: 'bottom' }`，该参数会改变对话框在 TinyMCE 编辑器内的呈现位置。

有关使用此属性的信息，请参阅“对话框配置文档”中的“对话框位置”部分。

更新 iframe 组件内容的推荐方法

更新 iframe 组件内容的推荐方法是：

`onAction: (api) => api.setData({ myiframe: '新内容' })`

1. 这将更新 iframe 以包含字符串 '新内容'。此文本可以是任何有效的 HTML。

2. onAction 是对话框规范中定义的回调函数。当对话框 body 内的按钮被触发时调用。

3. myiframe 是此规范中 iframe 组件的名称。

对话框位置

默认情况下，对话框会以模态形式显示在编辑器视口中央。

可以通过向 editor.windowManager.open() 提供第二个参数并设置合适的值来更改此呈现位置。

inline

传递给 editor.windowManager.open() 的 inline 选项会将对话框的呈现位置设定为两种可能性之一。

当在配置中添加值为 toolbar 时，它会将对话框设置为显示在 TinyMCE 工具栏旁边。

当在配置中添加值为 bottom 时，它会将对话框设置为显示在编辑器视窗的底部。

类型： String

可能的值： toolbar, bottom

添加了 inline 参数并将其设置为 toolbar 的基本示例

tinymce.activeEditor.windowManager.open({
  title: 'Dialog Title', // The dialog's title - displayed in the dialog header
  body: {
    type: 'panel', // The root body type - a Panel or TabPanel
    items: [ // A list of panel components
      {
        type: 'htmlpanel', // an HTML panel component
        html: 'Panel content goes here.'
      }
    ]
  },
  buttons: [ // A list of footer buttons
    {
      type: 'submit',
      text: 'OK'
    }
  ]
}, { inline: 'toolbar' });