trix
每天写作的丰富文本编辑器
在您的Web应用程序中撰写精美格式的文本。 trix是Wysiwyg的编辑器,用于编写消息,评论,文章和列表 - 简单的文档大多数Web应用程序都是由。它具有复杂的文档模型,对嵌入式附件的支持,并输出简短和一致的HTML。
trix是一个来自37 signals的开源项目,Ruby on Rails的创建者。成千上万的人信任我们的文字,我们建立了trix ,以赋予他们最好的编辑体验。参见Basecamp 3中的trix 。
设计不同
当trix于2014年设计时,大多数Wysiwyg编辑都是由Microsoft设计的HTML的可满足和execcommand API的包装纸,该版本是由Microsoft设计的,旨在支持Internet Explorer 5.5中网页的实时编辑,并最终对其他浏览器进行反向工程和副本。
由于这些API尚未完全指定或记录,并且由于Wysiwyg HTML编辑器的范围很大,因此每个浏览器的实现都有其自己的错误和怪癖集,并且JavaScript开发人员可以解决不一致之处。
trix通过将可满足的设备视为I/O设备来避开这些不一致之处:当输入进入编辑器时, trix将输入转换为其内部文档模型的编辑操作,然后将文档重新呈现为编辑器。这trix完全控制每次击键之后发生的事情,并避免使用ExecCommand的需求。
这是所有现代生产,Wysiwyg编辑现在采用的方法。
建立在网络标准上
trix支持所有常绿,自我更新的桌面和移动浏览器。
trix具有既定的Web标准,尤其是自定义元素,元素内部,突变观察者和承诺。
入门
trix以ESM和UMD格式捆绑在一起,并与任何资产包装系统一起使用。
从trix开始的最简单方法是从页面的<头>中的NPM CDN中包括它:
< head >
…
< link rel =" stylesheet " type =" text/css " href =" https://un***pkg.com/trix@2.0.8/dist/ trix .css " >
< script type =" text/javascript " src =" https://un***pkg.com/trix@2.0.8/dist/ trix .umd.min.js " > script >
head >
trix .CSS包括trix工具栏,编辑器和附件的默认样式。如果您想自己定义这些样式,请跳过此文件。
另外,您可以安装NPM软件包并将其导入您的应用程序:
import trix from " trix "
document . addEventListener ( " trix -before-initialize" , ( ) => {
// Change trix .config if you need
} )
创建编辑器
将空的< trix -editor> trix -editor>标记放在页面上。 trix将在编辑器之前自动插入一个单独的< trix -toolbar>。
就像html
创建工具栏
trix会自动为您创建工具栏,并在< trix -editor>元素之前将其附加。如果您想将工具栏放在其他地方,则可以使用工具栏属性:
< main >
< trix -toolbar id =" my_toolbar " > trix -toolbar >
< div class =" more-stuff-inbetween " > div >
< trix -editor toolbar =" my_toolbar " input =" my_input " > trix -editor >
main >
要更改工具栏而无需修改trix ,您可以覆盖trix .config.toolbar.getDefaulthtml()函数。默认工具栏html在config/toolbar.js中。 trix使用数据属性来确定如何响应工具栏按钮。
切换属性
使用Data trix -attribute =“ <属性名称>”,您可以在当前选择中添加一个属性。例如,要将粗体样式应用于所选文本的按钮是:
< button type =" button " class =" bold " data- trix -attribute =" bold " data- trix -key =" b " > button >
trix将确定选择了一系列文本,并将应用在trix .config.textattributes中定义的格式(在config/text_attributes.js中找到)。
data trix -key =“ b”告诉trix ,当您使用meta + b时,应应用此属性。
如果属性是在trix .config.blockattributes中定义的, trix将将属性应用于文本的当前块。
< button type =" button " class =" quote " data- trix -attribute =" quote " > button >单击报价按钮切换是否应使用
渲染块。与元素内部集成
trix将根据浏览器对元素内部的支持,将< trix -editor>元素与表单集成在一起。如果需要禁用对ElementInternals的支持,请设置trix .elements。 trix editorelement.formassified = false:
trix " trix .elements. trix EditorElement.formAssociated = false">import trix from " trix " trix . elements . trix EditorElement . formAssociated = false调用内部trix动作
内部操作是在控制器/editor_controller.js中定义的,包括:
- 撤消
- 重做
- 关联
- 增加blocklevel
- 降低blocklevel
< button type =" button " class =" block-level decrease " data- trix -action =" decreaseBlockLevel " > button >调用外部自定义操作
如果要在工具栏中添加一个按钮并将其调用外部操作,则可以使用X-将操作名称前缀。例如,如果我想在单击新按钮时打印一个日志语句,我将通过按钮的数据属性设置为数据trix -action =“ x-log”
< button id =" log-button " type =" button " data- trix -action =" x-log " > button >要响应该动作,请聆听trix -action -Action -invoke。事件的目标属性返回对< trix -editor>元素的引用,其InvokingElement属性返回对
trix-action-invoke", function(event) { const { target, invokingElement, actionName } = event if (actionName === "x-log") { console.log(`Custom ${actionName} invoked from ${invokingElement.id} button on ${target.id} trix -editor`) } })">document . addEventListener ( " trix -action-invoke" , function ( event ) { const { target , invokingElement , actionName } = event if ( actionName === "x-log" ) { console . log ( `Custom ${ actionName } invoked from ${ invokingElement . id } button on ${ target . id } trix -editor` ) } } )与形式集成
要提交带有表单的< trix -editor>的内容,请首先在表单中定义隐藏的输入字段,然后为其分配一个ID。然后在编辑器的输入属性中引用该ID。
trix -editor> ">< form … > < input id =" x " type =" hidden " name =" content " > < trix -editor input =" x " > trix -editor > form >trix将自动更新隐藏输入字段的值,每个更改为编辑器。
用存储的内容填充
要用存储的内容填充< trix -editor>,请在关联的输入元素的值属性中包含该内容。
trix -editor> ">< form … > < input id =" x " value =" Editor content goes here " type =" hidden " name =" content " > < trix -editor input =" x " > trix -editor > form >始终使用关联的输入元素安全填充编辑器。 trix不会在< trix -editor>… trix -editor>标签中加载任何HTML内容。
验证编辑器
开箱即用,< trix -editor>元素支持浏览器的内置约束验证。当使用所需属性渲染时,当编辑器完全空时,编辑器将无效。例如,考虑以下HTML:
trix -editor>">< input id =" x " value ="" type =" hidden " name =" content " > < trix -editor input =" x " required > trix -editor >由于< trix -editor>元素是[必需的],因此当其值为空时,它是无效的:
trix-editor") editor.validity.valid // => false editor.validity.valueMissing // => true editor.matches(":valid") // => false editor.matches(":invalid") // => true editor.value = "A value that isn't empty" editor.validity.valid // => true editor.validity.valueMissing // => false editor.matches(":valid") // => true editor.matches(":invalid") // => false">const editor = document . querySelector ( " trix -editor" ) editor . validity . valid // => false editor . validity . valueMissing // => true editor . matches ( ":valid" ) // => false editor . matches ( ":invalid" ) // => true editor . value = "A value that isn't empty" editor . validity . valid // => true editor . validity . valueMissing // => false editor . matches ( ":valid" ) // => true editor . matches ( ":invalid" ) // => false除了内置的[必需]属性外,< trix -editor>元素还通过其setCustomVality方法支持自定义验证。例如,考虑以下HTML:
trix -editor>">< input id = "x" value = "" type = "hidden" name = "content" > < trix -editor input = "x" > trix -editor >可以随时进行自定义验证。例如,在编辑内容更改后触发trix -Change事件后,可以进行验证:
trix-change", (event) => { const editorElement = event.target const trix Document = editorElement.editor.getDocument() const isValid = ( trix Document) => { // determine the validity based on your custom criteria return true } if (isValid( trix Document)) { editorElement.setCustomValidity("") } else { editorElement.setCustomValidity("The document is not valid.") } }">addEventListener ( " trix -change" , ( event ) => { const editorElement = event . target const trix Document = editorElement . editor . getDocument ( ) const isValid = ( trix Document ) => { // determine the validity based on your custom criteria return true } if ( isValid ( trix Document ) ) { editorElement . setCustomValidity ( "" ) } else { editorElement . setCustomValidity ( "The document is not valid." ) } }禁用编辑器
要禁用< trix -editor>,请使用[disabled]属性:
trix -editor>">< trix -editor disabled > trix -editor >禁用的编辑器不是可编辑的,无法接收焦点,并且当提交相关<形式>元素时,其价值将被忽略。
要更改编辑器是否被禁用,请切换[禁用]属性或为.disabled属性分配布尔值:
trix -editor> ">< trix -editor id =" editor " disabled > trix -editor > < script > const editor = document . getElementById ( "editor" ) editor . toggleAttribute ( "disabled" , false ) editor . disabled = true script >禁用时,编辑器将匹配:禁用的CSS伪级。
提供一个可访问的名称
像其他表单控件一样,< trix -editor>元素应具有可访问的名称。 < trix -editor>元素与
- 呈现< trix -editor>元素具有[id]属性,该属性是
元素通过其[for]属性的引用: trix -editor>">< label for =" editor " > Editor label > < trix -editor id =" editor " > trix -editor >
- 渲染< trix -editor>元素作为
元素的孩子: trix -toolbar>Editor < trix -editor toolbar="editor-toolbar"> trix -editor> ">< trix -toolbar id =" editor-toolbar " > trix -toolbar > < label > Editor < trix -editor toolbar =" editor-toolbar " > trix -editor > label >警告
将< trix -editor>元素作为
元素的孩子呈现时,明确呈现相应的< trix -toolbar>元素 元素之外。 除了与
元素集成外,< trix -editor>元素支持[aria-label]和[aria-labelledby]属性。 样式格式的内容
为了确保您在保存时看到的是所看到的内容,请使用CSS类名称来示例样式的trix格式化内容。将此类名称应用于您的< trix -editor>元素,并在渲染存储的trix内容以在应用程序中显示时包含元素。
trix -content"> trix -editor>">< trix -editor class =" trix -content " > trix -editor >< div class =" trix -content " > Stored content here div >默认的trix .css文件包括基本格式化内容的样式,包括子弹和编号列表,代码块和块引号 - 在class name trix -content下。我们鼓励您将这些样式用作起点,将它们复制到应用程序的CSS中,具有不同的类名称。
存储附件的文件
trix会自动接受已拖动或粘贴到编辑器中的文件,并将其插入文档中的附件。每个附件都被视为待处理,直到您将其远程存储并为trix提供永久性URL。
要存储附件,请收听trix -Attachment -Add事件。用XMLHTTPRequest上载附件的文件,并在完成后设置附件的URL属性。有关详细信息,请参见附件示例。
如果您不想接受删除或粘贴的文件,请在trix -file -peccept Event上致电Trix -File -File -peccept事件,该trix在trix -Attachment -Add事件之前派发。
通过编程编辑文本
您可以通过trix .Editor界面对trix编辑器进行编程操作,并在每个< trix -editor>元素上通过其编辑器属性提供。
trix-editor") element.editor // is a trix .Editor instance">var element = document . querySelector ( " trix -editor" ) element . editor // is a trix .Editor instance了解文档模型
trix编辑器的格式化内容被称为文档,并表示为trix .Document类的实例。要获取编辑器的当前文档,请使用editor.getDocument方法。
element . editor . getDocument ( ) // is a trix .Document instance您可以使用document.tostring方法将文档转换为未形式的JavaScript字符串。
var document = element . editor . getDocument ( ) document . toString ( ) // is a JavaScript string不变性和平等
文档是不变的值。您在编辑器中进行的每个更改都用新文档代替了上一个文档。捕获编辑器内容的快照就像保留对其文档的参考一样简单,因为该文档永远不会随着时间的流逝而改变。 (这就是trix实现撤消的方式。)
要比较两个文档以保持平等,请使用document.isequalto方法。
var document = element . editor . getDocument ( ) document . isEqualTo ( element . editor . getDocument ( ) ) // true获取和设置选择
trix文档构成为单独寻址字符的序列。文档中一个字符的索引称为位置,一个开始和端位置共同组成范围。
要获取编辑器的当前选择,请使用editor.getSelectedRange方法,该方法返回包含开始和终点位置的两元素数组。
element . editor . getSelectedRange ( ) // [0, 0]您可以通过将范围阵列传递到editor.setselectedRange方法来设置编辑器的当前选择。
// Select the first character in the document element . editor . setSelectedRange ( [ 0 , 1 ] )崩溃的选择
当范围的开始和端位置相等时,据说范围崩溃了。在编辑器中,一个崩溃的选择是闪烁的光标,而不是突出显示的文本。
为了方便起见,在使用折叠选择时,以下对SetSelectedRange的调用等效:
element . editor . setSelectedRange ( 1 ) element . editor . setSelectedRange ( [ 1 ] ) element . editor . setSelectedRange ( [ 1 , 1 ] )方向运动
要通过文档进行编程方式移动光标或选择,请致电Editor.movecursorindirection或Editor.spandselectionDirection方法,具有方向参数。方向可以是“前进”或“向后”。
// Move the cursor backward one character element . editor . moveCursorInDirection ( "backward" ) // Expand the end of the selection forward by one character element . editor . expandSelectionInDirection ( "forward" )将位置转换为像素偏移
有时,您需要在编辑器中给定位置的角色的X和Y坐标。例如,您可能需要绝对将弹出菜单元素放在编辑器的光标下方。
调用带有位置参数的getClientRectAtposition方法,以获取代表给定位置处角色的左侧和顶部偏移,宽度和高度的DOMRECT实例。
var rect = element . editor . getClientRectAtPosition ( 0 ) [ rect . left , rect . top ] // [17, 49]插入和删除文本
编辑器接口提供了用于当前选择中插入,替换和删除文本的方法。
要插入或替换文本,请首先设置所选范围,然后调用下面的插入方法之一。 trix将首先删除任何选定的文本,然后将新文本插入所选范围的开始位置。
插入纯文本
要将未形式的文本插入文档中,请致电editor.insertstring方法。
// Insert “Hello” at the beginning of the document element . editor . setSelectedRange ( [ 0 , 0 ] ) element . editor . insertString ( "Hello" )插入HTML
要将HTML插入文档中,请致电editor.inserthtml方法。 trix将首先将HTML转换为其内部文档模型。在此转换过程中,任何在trix文档中无法表示的格式都将丢失。
// Insert a bold “Hello” at the beginning of the document element . editor . setSelectedRange ( [ 0 , 0 ] ) element . editor . insertHTML ( "Hello" )插入文件
要将DOM文件对象插入文档中,请调用editor.intertfile方法。 trix会插入文件的待处理附件,就像您已将其拖放并将其丢弃到编辑器上一样。
// Insert the selected file from the first file input element var file = document . querySelector ( "input[type=file]" ) . file element . editor . insertFile ( file )插入内容附件
内容附件是HTML的独立单位,其行为就像编辑器中的文件一样。它们可以被移动或删除,但不能直接进行编辑,并且由文档模型中的单个字符位置表示。
要插入HTML作为附件,请创建带有内容属性的trix .Attachment,然后调用editor.insertattachment方法。内容附件中的HTML不受trix的文档转换规则的约束,并且将呈现为IS。
@插入线路休息
要插入线路断开,请调用editor.insertline break方法,该方法在功能上等同于按返回键。
// Insert “Hellon” element . editor . insertString ( "Hello" ) element . editor . insertLineBreak ( )删除文字
如果当前选择崩溃,则可以使用Editor.DeleteDirection方法在光标之前或之后模拟删除文本。
// “Backspace” the first character in the document element . editor . setSelectedRange ( [ 1 , 1 ] ) element . editor . deleteInDirection ( "backward" ) // Delete the second character in the document element . editor . setSelectedRange ( [ 1 , 1 ] ) element . editor . deleteInDirection ( "forward" )要删除一系列文本,请首先设置选定的范围,然后以任何方向为参数调用Editor.Deleter.DeleteDirection。
// Delete the first five characters element . editor . setSelectedRange ( [ 0 , 4 ] ) element . editor . deleteInDirection ( "forward" )使用属性和嵌套
trix表示格式为文档范围内应用的属性集。
默认情况下, trix支持内联属性粗体,斜体,HREF和罢工,以及块级属性heading1,Quote,quote,code,code,bullet和number。
应用格式
要将格式应用于当前选择,请使用editor.activateattribute方法。
element . editor . insertString ( "Hello" ) element . editor . setSelectedRange ( [ 0 , 5 ] ) element . editor . activateAttribute ( "bold" )要设置HREF属性,请将URL作为第二个参数传递给Editor.activateatTribute。
trix") element.editor.setSelectedRange([0, 4]) element.editor.activateAttribute("href", "https://trix*-e**ditor.org/")">element . editor . insertString ( " trix " ) element . editor . setSelectedRange ( [ 0 , 4 ] ) element . editor . activateAttribute ( "href" , "https://trix*-e**ditor.org/" )删除格式
使用editor.deactivateattribute方法从选择中删除格式。
element . editor . setSelectedRange ( [ 2 , 4 ] ) element . editor . deactivateAttribute ( "bold" )用崩溃的选择格式化
如果当选择折叠时激活或停用属性,则格式化更改将适用于任何后续呼叫对editor.insertstring插入的文本。
element . editor . activateAttribute ( "italic" ) element . editor . insertString ( "This is italic" )调整嵌套水平
要调整引号,项目符号列表或编号列表的嵌套级别,请致电Editor.increasenestinglevel和editor.decreasenestinglevel方法。
element . editor . activateAttribute ( "quote" ) element . editor . increaseNestingLevel ( ) element . editor . decreaseNestingLevel ( )使用撤消和重做
trix编辑器支持无限的撤消和重做。连续打字和格式变化以五秒的间隔合并在一起;所有其他输入更改均在撤消历史记录中单独记录。
致电editor.undo和editor.redo方法执行撤消或重做操作。
element . editor . undo ( ) element . editor . redo ( )您通过编辑器接口进行的更改不会自动记录撤消条目。您可以通过使用描述参数调用editor.recordundoentry方法来保存自己的撤消条目。
element . editor . recordUndoEntry ( "Insert Text" ) element . editor . insertString ( "Hello" )加载和保存编辑状态
用JSON.Stringify和Restore Saved State用editor.loadjson方法序列化编辑器的状态。序列化状态包括文档和当前选择,但不包括撤消历史记录。
下载源码通过命令行克隆项目:
git clone https://github.com/basecamp/trix.git