配置参考 \ UI界面配置配置编辑器的外观,包括菜单和工具栏

此页更新时间:2020-12-25 16:23

此页英文文档:https://www.tiny.cloud/docs/configure/editor-appearance/

配置编辑器的外观,包括菜单和工具栏:

block_formats(区块列表)

用于配置“菜单:格式→区块”中的选项(非菜单:格式→格式→区块)。它的值形如:title=block,多个用分号分隔。

取值:String

默认:'Paragraph=p;Heading 1=h1;Heading 2=h2;Heading 3=h3;Heading 4=h4;Heading 5=h5;Heading 6=h6;Preformatted=pre'

tinymce.init({
    selector: '#textarea1',
    block_formats: 'Paragraph=p;Header 1=h1;Header 2=h2;Header 3=h3',
});

branding(隐藏右下角技术支持)

设为false时,隐藏编辑器界面右下角的“Powered by Tiny”(官方汉化为:由Tiny驱动)字样。

为支持TinyMCE推广,建议保留。

取值:true/false

默认值:true

tinymce.init({
    selector: '#textarea1',
    branding: false,
});

contextmenu(上下文菜单)

指定上下文菜单出现的项目。所谓上下文菜单,就是在编辑器内容出现的右键关联菜单。在当鼠标在链接上时是编辑链接,当鼠标在表格上时是编辑表格。菜单可根据不同的环境出现不同的内容。

其值为任何已注册的菜单项,允许使用“|”作为分隔。

取值:String

默认:link image imagetools table spellchecker

tinymce.init({
    selector: '#textarea1',
    contextmenu: "bold copy ",
});

contextmenu_avoid_overlap

5.5新增

该选项可防止上下文菜单覆盖(或重叠)编辑器中的特定节点。此选项接受CSS选择器。在与指定选择器匹配的节点上打开关联菜单时,关联菜单将呈现在节点下方,而不是单击发生的位置。如果节点下方的浏览器窗口中没有足够的空间,则关联菜单将显示在节点上方。

取值:String

默认:''

tinymce.init({
    selector: '#textarea1',
    contextmenu_avoid_overlap: '.mce-spelling-word'
});

contextmenu_never_use_native

在编辑器中屏蔽浏览器本身的右键菜单

警告:此选项可能会导致单击右键时出现意外行为。

取值:true/false

默认:false

tinymce.init({
    selector: '#textarea1',
    contextmenu_never_use_native: true
});

custom_ui_selector

此选项可指定某些元素成为编辑器的一部分,当焦点移动到此选择器匹配的元素上时,不会触发编辑器的blur事件。

取值:String

tinymce.init({
    selector: '#textarea1',
     custom_ui_selector: '.my-custom-button'
});
...
<textarea id="textarea1"></textarea>
<button class="my-custom-button">Button</button>

draggable_modal(模态窗口允许拖动)

5.0.13新增。

为tinymceUI的模态窗口添加拖动模式。默认是关闭的。

取值:true/false

默认:false

tinymce.init({
    selector: '#textarea1',
    draggable_modal: true
});

elementpath(隐藏底栏的元素路径)

设为false时,可隐藏底栏的元素路径

取值:true/false

默认:true

tinymce.init({
    selector: '#textarea1',
    elementpath: false
});

event_root

当编辑器使用内联模式(inline)时,使用此配置可指定一个根节点,编辑器事件只在该根节点下与selector匹配的DOM中响应。

取值:String

上面说的比较难懂,看个例子:

tinymce.init({
    selector: '.editor',
    inline: true,
    event_root: '#root',
});
......
<div class="editor" >TinyMCE示例</div>
<div id="root"><div class="editor" >TinyMCE示例</div></div>

▲通过init将两个.editor创建为编辑器实例,但当鼠标分别点击两个div时,只有在#root内的div才会出现菜单和工具栏。

fixed_toolbar_container

5.0.2新增

指定工具栏在某一容器顶部固定。

取值:String (css选择器)

tinymce.init({
    selector: '.editor',
    inline: true,
    fixed_toolbar_container: '#mytoolbar'
});

font_formats(字体列表)

配置编辑器可选则的字体列表。格式为:标题1=字体名1,字体名2可多个;标题2=字体名3

每一项用分号分隔,字体名之间用逗号分隔。字体名写法可参考CSS的font-family。

取值:String

默认:'Andale Mono=andale mono,times;Arial=arial,helvetica,sans-serif;Arial Black=arial black,avant garde;Book Antiqua=book antiqua,palatino;Comic Sans MS=comic sans ms,sans-serif;Courier New=courier new,courier;Georgia=georgia,palatino;Helvetica=helvetica;Impact=impact,chicago;Symbol=symbol;Tahoma=tahoma,arial,helvetica,sans-serif;Terminal=terminal,monaco;Times New Roman=times new roman,times;Trebuchet MS=trebuchet ms,geneva;Verdana=verdana,geneva;Webdings=webdings;Wingdings=wingdings,zapf dingbats'

tinymce.init({
    selector: '#textarea1',//这是中文字体的一个例子
    font_formats: '微软雅黑=Microsoft YaHei,Helvetica Neue,PingFang SC,sans-serif;苹果苹方=PingFang SC,Microsoft YaHei,sans-serif;宋体=simsun,serif',
});

fontsize_formats(文字大小列表)

定义字体大小列表的项目,每一项用空格分隔。数值单位与CSS写法相同。

取值:String

默认: '11px 12px 14px 16px 18px 24px 36px 48px'

tinymce.init({
    selector: '#textarea1',
    toolbar: 'fontsizeselect',
    fontsize_formats: '11px 12px 14px 16px 18px 24px 36px 48px',
});

icons(为tinymce附加新图标集合)

5.0.5新增。

该选项允许你扩展tinymce的默认图标库,新附加的图标具有更高的优先级,可以部分替换当前系统内的图标,实现tinymce的局部定制化。

该参数的实现与加载方式类似。不是指定图标的js文件,而是指定图标文件所在的文件夹。

tinymce将在初始化时从 《tinymce根目录/icons/该参数值/icons.js》中加载图标。

所以该值类似于主题名称。

取值:String

tinymce.init({
    selector: '#iconsdemo',
    icons: 'custom'      // baseURL/icons/custom/icons.js
});

icons_url(附加新图标的url路径)

5.0.6新增。

通过一个url来指定图标js文件的所在位置。

但设置该参数以后,还需要再用icons一次,这和引入外部语言包的用法一致。

取值:String

tinymce.init({
    selector: '#textarea1',
    icons_url: '/icons/custom/icons.js', // load icon pack
    icons: 'custom'      // baseURL/icons/custom/icons.js
});

inline(内联模式)

开启内联模式,详见:内联模式

取值:true/false

默认:false

lineheight_formats(行高列表)

5.5新增

为行高下拉菜单指定对应的行高的值。

取值:String

默认:'1 1.1 1.2 1.3 1.4 1.5 2'

lineheight_formats: '1 1.2 1.5 1.6 1.8 2 2.4'

width&height(设置宽高)

如参数只提供数字,则默认单位为像素(px),如提供了单位,TinyMCE会以css模式去理解它。单位支持px/%/em/vh/vw

取值:Number或String

默认:width默认是100%,height通常为200px。

tinymce.init({
    selector: '#textarea1',
    width: 300,
    height: 300,
});

max_width&max_height(最大宽高)

min_width&min_height(最小宽高)

根据autoresize插件启用与否,max_height和min_height会存在两种不同的行为:

  • 不存在autoresize插件(默认):控制的是用户通过编辑器右下角控件可拖拽的最大最小高度。
  • 使用autoresize插件:控制编辑器自动伸缩的最大最小高度。
注:此参数默认设置的是可编辑区域,而不是整个编辑器

取值:Number / String

指定菜单栏及下拉菜单上放置的项目(其还提供创建自定义标题菜单的方法)。

其值是一个包含菜单项目的对象,由 菜单项:{标题,子菜单项} 组成。

取值:Object

tinymce.init({
    selector: '#textarea1',
    menu: {
        file: {title: '文件', items: 'newdocument'},
        edit: {title: '编辑', items: 'undo redo | cut copy paste pastetext | selectall'},
        insert: {title: '插入', items: 'link media | template hr'},
        view: {title: '查看', items: 'visualaid'},
        format: {title: '格式', items: 'bold italic underline strikethrough superscript subscript | formats | removeformat'},
        table: {title: '表格', items: 'inserttable tableprops deletetable | cell row column'},
        tools: {title: '工具', items: 'spellchecker code'}
    }
});

自定义菜单项:

tinymce.init({
    selector: '#textarea1',
    menubar: 'my1',
    menu: {
        my1: {title: '我的菜单', items: 'copy paste' }
    }
});
如果只需要指定哪些一级菜单显示,或调整菜单顺序,可使用menubar。

指定哪些一级菜单显示,或调整菜单顺序。

取值:String

tinymce.init({
    selector: '#textarea1',
    menubar: 'file edit insert view format table tools help'
});
如要隐藏菜单栏,将其值设为false即可。

mobile(移动端配置)

当tinymce检测到当前环境为移动设备时,该参数允许你配置在移动设备生效配置参数。

取值:Object

tinymce.init({
    selector: '#textarea1',
    plugins: [ 'code', 'lists' ],
    mobile: {
        plugins: [ 'autosave', 'lists', 'autolink' ],
        toolbar: [ 'undo', 'bold', 'italic', 'styleselect' ]
    }
});

placeholder(内容预展示文本)

5.2新增

取值:String

默认:''

tinymce.init({
    selector: '#textarea1',
    placeholder: '请再次输入内容',
});

preview_styles(菜单[格式]预览样式)

取值:false / String

默认:font-family font-size font-weight font-style text-decoration text-transform color background-color border border-radius outline text-shadow

tinymce.init({
    selector: '#textarea1',
    preview_styles: false,
});

quickbars_insert_toolbar([插入]快捷工具栏)

quickbars_selection_toolbar([选择]快捷工具栏)

在编辑器内容区,光标插入(回车)或选择时,在光标位置出现的快捷工具栏。

可使用任何在工具栏(toolbar)中可用的项目。

使用该选项必须先启用quickbars插件。

取值:String

默认:见下方示例

tinymce.init({
    selector: '#textarea1',
    inline: true,
    plugins: 'quickbars',
    quickbars_insert_toolbar: 'quickimage quicktable',
    quickbars_selection_toolbar: 'bold italic | quicklink h2 h3 blockquote',
});

removed_menuitems(移除某菜单项)

用于从下拉菜单中移除某些菜单项。当配合menu来创建动态菜单时此选项可能有用。

取值:String

tinymce.init({
    selector: '#textarea1',
    removed_menuitems: 'undo, redo',
});

resize(调整编辑器大小工具)

在编辑器右下角有一个可以拖动的标记,鼠标按住它可以改变编辑器的大小。默认resize: true

可选值为:true(仅允许改变高度), false(完全不让你动), 'both'(宽高都能改变,注意引号)

如要禁止用户拖动改变编辑器大小,设为false即可。

取值:true/false/'both'

默认:true

tinymce.init({
    selector: '#textarea1',
    resize: 'both',
});

skin(设置皮肤)

为TinyMCE指定皮肤,v5默认皮肤是“oxide”,它包含浅色版本和深色版本。深色版本名为“oxide-dark”

指定的皮肤应在TinyMCE的/skin/ui文件夹内,如不存在,TinyMCE将使用默认皮肤。

取值:String

tinymce.init({
    selector: '#textarea1',
    skin: 'oxide-dark',
});

示例可参考:自定义界面(UI)这一节。

skin_url(引入外部皮肤)

如果皮肤未存在上述文件夹内,可使用该选项,用URL指定一个皮肤的位置。

取值:String

tinymce.init({
    selector: '#textarea1',
    skin_url: '/css/mytinymceskin',
});

statusbar(显示隐藏状态栏)

状态栏指的是编辑器最底下、左侧显示dom信息、右侧显示Tiny版权链接和调整大小的那一条。默认是显示的,设为false可将其隐藏。

取值:ture/false

默认:ture

tinymce.init({
    selector: '#textarea1',
    statusbar: false
});

style_formats(自定义段落样式格式)

注意,这货与formats的写法规则差不多,但定义的东西不一样。这货定义后出现在段落选项里。formats则是改写默认格式。

光说是难理解的,上个DEMO:

tinymce.init({
    selector: '#textarea1',
    plugins:'code',
    style_formats: [
        {title: 'Bold text', inline: 'b'},
        {title: 'Red text', inline: 'span', styles: {color: '#ff0000'}},
        {title: 'Red header', block: 'h1', styles: {color: '#ff0000'}},
        {title: 'Example 1', inline: 'span', classes: 'example1'},
        {title: 'Example 2', inline: 'span', classes: 'example2'},
        {title: '首行缩进', block: 'p', styles: {'text-indent': '2em'}},
        {title: 'Table styles'},
        {title: 'Table row 1', selector: 'tr', classes: 'tablerow1'}
    ],
    style_formats_merge: true,
    style_formats_autohide: true,
});

style_formats_merge(替换还是附加到自定义段落样式列表)

翻译成这么长一串,意思表达清楚就好。该选项的作用就是上面定义的style_formats是覆盖掉默认的列表,还是在默认列表后面附加自定义的配置。

取值:true/false

默认:false

例子见上面style_formats例子那段代码。

style_formats_autohide(隐藏当前不可用的样式列表)

该选项设为true时自动隐藏与当前选择内容不匹配的样式。

取值:true/false

默认:false

例子见上面style_formats例子那段代码。在style_formats定义了一个仅作用于tr的样式"Table row 1",但当前选择块的内容不包含tr,所以列表中隐藏了"Table row 1"。

theme(设置主题)

指定应用的主题,TinyMCE默认的主题名为:“Silver”。有关皮肤和主题的区别,可参考:自定义界面(UI)这一节。

指定的主题应在TinyMCE的/theme文件夹内,如不存在,TinyMCE将使用默认主题。

取值:String

tinymce.init({
    selector: '#textarea1',
    theme:'silver',
});

theme_url(引入外部主题)

如果主题未存在上述文件夹内,可使用该选项,用URL指定一个主题的位置。

取值与皮肤指定文件夹不同,需要具体到js文件。

取值:String

tinymce.init({
    selector: '#textarea1',
    theme_url: '/mytheme/mytheme.js'
});

toolbar(自定义工具栏)

指定工具栏上显示的按钮,使用空格分隔,用 | 分组。

如要隐藏菜单栏,将其值设为false即可。

取值:String / Array / false

tinymce.init({
    selector: '#textarea1',
    toolbar: 'undo redo | styleselect | bold italic ',
});

数组写法

tinymce.init({
    selector: '#textarea1',
    toolbar: [ //数组写法
        'undo redo | styleselect | bold italic | link image',
        'alignleft aligncenter alignright'
    ]
});

toolbar(n)写法

tinymce.init({
    selector: '#textarea1',
    toolbar1: 'undo redo | styleselect | bold italic | link image',
    toolbar2: 'alignleft aligncenter alignright',
});

工具栏的更详细说明和示例可参考:基本设置这一节。

toolbar_drawer(工具栏抽屉模式:已废除)

生于5.0.2,死于5.2.0。

将第一行放不下的工具栏按钮缩进抽屉(3个点的图标)里。

该参数提供两种模式,例子见下面的toolbar_mode部分。

取值:floating / sliding / false

自5.1.0开始抽屉模式默认开启,默认参数为:floating

5.2.0目前还对该参数进行了兼容,但未来后续版本中随时会取消,请及时变更到toolbar_mode。

toolbar_mode(工具栏模式)

自5.2.0起用于替代上面的toolbar_drawer。

默认wrap不收缩工具栏,取值为floating或sliding时,将第一行放不下的工具栏按钮缩进抽屉(3个点的图标)里,scrolling则采用移动端的横线滚动方式。

该参数提供三种模式,通过下面的例子体验下三种模式的不同吧。

取值:floating / sliding / scrolling / wrap

自5.2.0开始默认参数为:wrap

工具栏floating模式。

工具栏sliding模式。

工具栏scrolling模式。

toolbar_location(工具栏位置,可实现在底部)

5.2新增。

选择工具栏上下位置。

取值:'' / 'bottom'

取值:'auto' (5.3.0新增)

默认:''(5.3.0默认:'auto')

auto参数作用:如果顶部没有空间,则工具栏和菜单栏将显示在底部(即行为同bottom)。

toolbar_groups(工具栏分组)

5.2新增。

该参数将颠覆现有的工具栏布局模式。

它的作用是,自定义一个新的工具栏按钮,当点击这个新的按钮时,出现横向的下拉按钮集合。

启用toolbar_groups会令toolbar_mode参数默认为floating,所以无需指定toolbar_mode。如果手动指定toolbar_mode为别的值,则自定义的工具栏分组全都不显示,并在console里给出错误提示。

不废话,先上例子:

tinymce.init({
    selector: '#tinydemo_group',
    language:'zh_CN',
    menubar: false,
    toolbar: 'formatting | alignment',
    toolbar_groups: {
        formatting: {
            text: '文字格式',
            tooltip: 'Formatting',
            items: 'bold italic underline | superscript subscript',
        },
        alignment: {
            icon: 'align-left',
            tooltip: 'alignment',
            items: 'alignleft aligncenter alignright alignjustify',
        },
    }
});

如上代码,我们配置了两个名为“formatting”和“alignment”新工具栏按钮,并分别配置了新按钮的几个参数。

  • text / icon :二者任选其一,作为新按钮在工具栏上展示的UI。
  • tooltip:鼠标悬停时的工具栏提示,可不写。
  • items:点击后出现的多个按钮,参数写法和toolbar参数是一模一样的,也支持字符串和数组两种形式。
5.2新增这东西,算是变相解决了日益增长的按钮数量和屏幕像素始终有限的矛盾,PC端还好些,手机端用途将非常大。。

toolbar_persist(内联模式始终显示工具栏)

5.5新增。

选项控制内联编辑器的工具栏和菜单栏的自动显示和隐藏行为。

默认禁用,当开启后内联模式下将始终显示工具栏和菜单栏,而不是在失去焦点时隐藏他们。

取值:true / false

默认:false

toolbar_sticky(粘性工具栏)

5.1新增。

粘性工具栏(或停靠工具栏),在向下滚动网页直到不再可见编辑器时,将工具栏和菜单停靠在屏幕顶部。

取值:true / false

默认:false

下一节:内容外观配置