.. _editor:

:wx_comp:`editor`
====================

.. versionadded:: 2.7.0 低版本需做 :ref:`compatibility` 。

富文本编辑器，可以对图片、文字进行编辑。

编辑器导出内容支持带标签的 ``html`` 和纯文本的 ``text`` ，编辑器内部采用 `delta`_ 格式进行存储。

通过 :func:`setContents <EditorContext.setContents>` 接口设置内容时，
解析插入的 ``html`` 可能会由于一些非法标签导致解析错误，
建议开发者在小程序内使用时通过 `delta`_ 进行插入。

.. _delta: https://wdk-docs.github.io/delta/

富文本组件内部引入了一些基本的样式使得内容可以正确的展示，开发时可以进行覆盖。

.. attention::
   在其它组件或环境中使用富文本组件导出的html时，
   需要额外引入 `这段样式 <https://github.com/wechat-miniprogram/editor-style/blob/master/editor.css>`_ ，
   并维护 ``<ql-container><ql-editor></ql-editor></ql-container>`` 的结构。

图片控件仅初始化时设置有效。

相关 api： :class:`EditorContext`

+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
|       属性       |    类型     | 默认值 | 必填 |                             说明                              | 最低版本 |
+==================+=============+========+======+===============================================================+==========+
| read-only        | boolean     | false  | 否   | 设置编辑器为只读                                              | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| placeholder      | string      |        | 否   | 提示信息                                                      | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| show-img-size    | boolean     | false  | 否   | 点击图片时显示图片大小控件                                    | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| show-img-toolbar | boolean     | false  | 否   | 点击图片时显示工具栏控件                                      | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| show-img-resize  | boolean     | false  | 否   | 点击图片时显示修改尺寸控件                                    | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| bindready        | eventhandle |        | 否   | 编辑器初始化完成时触发                                        | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| bindfocus        | eventhandle |        | 否   | 编辑器聚焦时触发，event.detail = {html, text, delta}          | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| bindblur         | eventhandle |        | 否   | 编辑器失去焦点时触发，detail = {html, text, delta}            | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| bindinput        | eventhandle |        | 否   | 编辑器内容改变时触发，detail = {html, text, delta}            | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+
| bindstatuschange | eventhandle |        | 否   | 通过 Context 方法改变编辑器内样式时触发，返回选区已设置的样式 | 2.7.0    |
+------------------+-------------+--------+------+---------------------------------------------------------------+----------+

编辑器内支持部分 ``HTML`` 标签和内连样式，不支持 ``class`` 和 ``id``

支持的标签
--------------

- 不满足的标签会被忽略，``<div>`` 会被转行为 ``<p>`` 储存。

+----------+------------------------------------------------------------------------+
|   类型   |                                  节点                                  |
+==========+========================================================================+
| 行内元素 | <span> <strong> <b> <ins> <em> <i> <u> <a> <del> <s> <sub> <sup> <img> |
+----------+------------------------------------------------------------------------+
| 块级元素 | <p> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <ol> <ul> <li>                  |
+----------+------------------------------------------------------------------------+

支持的内连样式
------------------

内联样式仅能设置在行内元素或块级元素上，不能同时设置。例如 ``font-size`` 归类为行内元素属性，在 p 标签上设置是无效的。

+----------+---------------------------------------------------------------------------------------+
|   类型   |                                         样式                                          |
+==========+=======================================================================================+
| 块级样式 | text-align direction margin margin-top margin-left margin-right margin-bottom         |
+----------+---------------------------------------------------------------------------------------+
|          | padding padding-top padding-left padding-right padding-bottom line-height text-indent |
+----------+---------------------------------------------------------------------------------------+
| 行内样式 | font font-size font-style font-variant font-weight font-family                        |
+----------+---------------------------------------------------------------------------------------+
|          | letter-spacing text-decoration color background-color                                 |
+----------+---------------------------------------------------------------------------------------+


.. tip:: 插入的 html 中事件绑定会被移除
.. tip:: formats 中的 color 属性会统一以 hex 格式返回
.. tip:: 粘贴时仅纯文本内容会被拷贝进编辑器
.. tip:: 插入 html 到编辑器内时，编辑器会删除一些不必要的标签，以保证内容的统一。例如<p><span>xxx</span></p>会改写为<p>xxx</p>
.. tip:: 编辑器聚焦时页面会被上推，系统行为以保证编辑区可见

示例代码
-----------

:download:`在开发者工具中预览效果 <https://developers.weixin.qq.com/s/siL4iemP7n8W>`

.. code:: html

  <editor
    id="editor"
    class="ql-container"
    placeholder="{{placeholder}}"
    showImgSize
    showImgToolbar
    showImgResize
    bindstatuschange="onStatusChange"
    read-only="{{readOnly}}"
    bindready="onEditorReady"
  ></editor>

.. code:: js

  Page({
    readOnlyChange() {
      this.setData({
        readOnly: !this.data.readOnly
      })
    },
    onEditorReady() {
      const that = this
      wx.createSelectorQuery().select('#editor').context(function (res) {
        that.editorCtx = res.context
      }).exec()
    },
    format(e) {
      const {name, value} = e.target.dataset
      if (!name) return
      // console.log('format', name, value)
      this.editorCtx.format(name, value)
    },
  })