# 弹出式上传插件
弹出式上传插件（PUP）是一个小文件，它允许通过一个小的 JavaScript 文件提供外部图片上传。
提示
当启用 PUP 时，路由 /plugin 会显示如何向其他网站添加图片上传功能的说明。
# 工作原理
PUP 将用户可编辑的内容与一个上传按钮绑定，该按钮将触发一个图片上传对话框，它将自动处理图片插入所需的代码。终端用户将体验到一个流畅和整洁的过程，而无需离开原网站。
# 支持的设备
PUP 应该可以在任何现代网络浏览器 (HTML5) 中工作，无论任何的用户设备（包括移动设备）。它已经过测试，并确认可以在 Windows、Mac、Linux 和 Android(Chrome) 上运行。
# 安装
基本安装很简单，只需将以下代码复制到目标网站的任何 HTML 部分。你可以在这段代码上添加自定义选项。
<script async src="//demo.chevereto.com/sdk/pup.js" data-url="https://demo.chevereto.com/upload"></script>
注意： 你需要编辑 src 和 data-url 来匹配你的 Chevereto 网站。
PUP 在 DOM 上工作，所以它没有任何服务器端的依赖性，可以安装在任何网站上。
# 自定义
所有插件定制都通过 Data attributes (opens new window)] 处理，您必须将其添加到 PUP 基础代码中。例如，要使用红色调色板，代码应如下所示：
<script async src="//demo.chevereto.com/sdk/pup.js" data-url="https://demo.chevereto.com/upload" data-palette="red"></script>
这适用于所有 PUP 选项。格式是 data-key，其中 key 是目标选项键，在这种情况下，调色板选项被声明为 data-palette 属性值。
# 选项
这是所有可用的插件密钥选项的列表
# url
目标 Chevereto 网站的 URL
| 类型 | 示例 |
|---|---|
| String | https://demo.chevereto.com |
# palette
按钮的命名调色板或以逗号分隔的颜色列表（HEX、RGB等）。当使用逗号分隔的颜色列表时，系统会将每种颜色绑定到一个%n颜色索引（从%1开始），您可以使用自定义CSS。
| 类型 | 值 | 默认值 |
|---|---|---|
| String | default clear turquoise green blue purple darkblue yellow orange red grey black | default |
# auto-insert
嵌入代码，自动插入目标可编辑内容中。使用 full、medium 或 thumbnail 的代码将链接到图片查看器页面。
使用 0 禁用自动插入
| 类型 | 值 | 默认值 |
|---|---|---|
| String | 0 viewer-links direct-links html-embed html-embed-full html-embed-medium html-embed-thumbnail bbcode-embed bbcode-embed-full bbcode-embed-medium bbcode-embed-thumbnail markdown-embed markdown-embed-full markdown-embed-medium markdown-embed-thumbnail | bbcode-embed-medium |
# sibling
同级 CSS 选择器，将其用作对应插入按钮的 DOM 节点的引用。默认情况下，按钮将被放置在相对于可编辑内容的位置。当定义了同级元素时，插件将搜索该元素，并将其作为按钮插入引用。
| 类型 | 示例 |
|---|---|
| String | .sibling |
# sibling-pos
相对于放置按钮的同级的位置
| 类型 | 值 | 默认值 |
|---|---|---|
| String | before after | after |
# vendor
已经命名的程序字符串
| 类型 | 值 | 默认值 |
|---|---|---|
| String | bbpress discourse discuz ipb mybb nodebb phpbb smf vanilla vbulletin woltlab xenforo | auto |
# mode
插件模式。默认情况下，插件绑定到任何匹配的编辑框。使用 manual 模式显式插入按钮并停止任何自动绑定。
| 类型 | 值 | 默认值 |
|---|---|---|
| String | auto manual | auto |
# target
目标可编辑内容的 CSS 选择器。手动插入按钮时使用
| 类型 | 示例 | 默认值 |
|---|---|---|
| String | .selector | auto |
# lang
按钮语言为双字母和四字母语言代码
| 类型 | 值 | 默认值 |
|---|---|---|
| String | ar cs de es fi fr id it ja nl pt_BR ru zh_CN zh_TW | auto |
# container-class
自定义按钮容器类名。它将 %cClass 绑定到模板栈
| 类型 | 示例 | 默认值 |
|---|---|---|
| String | className | chevereto-pup-container |
# button-class
自定义按钮类名。它将 %bClass 绑定到模板栈
| 类型 | 示例 | 默认值 |
|---|---|---|
| String | className | chevereto-pup-button |
# html
| 类型 | 示例 |
|---|---|
| String | <div>Button<div> |
# css
| 类型 | 示例 |
|---|---|
| String | .div { color: red; } |
# fit-editor
一个布尔（逻辑）值，表示插件是否应该将按钮安装到目标编辑器工具栏上。
当禁用时，插件不会将按钮的样式与目标编辑器匹配（覆盖仅对已支持的程序有效）。
| 类型 | 值 |
|---|---|
| Integer | 0 1 |
# observe
用于元素的 CSS 选择器，在点击事件中会触发同级观察，然后插入按钮（实时追加）。对于动态编辑器来说很有用，因为它可以快速生成编辑框。
| 类型 | 示例 |
|---|---|
| String | .selector |
# observe-cache
一个布尔（逻辑）值，表示是否应缓存匹配的观察元素
启用时，它将停止观察匹配的观察到的元素单击事件。如果编辑器是动态生成的，并且没有存储为 DOM 节点，请始终禁用观察缓存。
| 类型 | 值 | 默认值 |
|---|---|---|
| Integer | 0 1 | 1 |
# 自定义 HTML 和 CSS
PUP支持模板占位符，这是一个特殊的字符串，PUP会将其转换为可用的标记。
可用的模板占位符：
| 标签 | 描述 |
|---|---|
| %x | PUP按钮观察器(必须用于触发按钮动作) |
| %cClass | 容器类名称 |
| %bClass | 按钮类名称 |
| %iClass | 图标类名称 |
| %iconSvg | 现成的 SVG HTML 标记形式的矢量图标 |
| %text | 翻译后的按钮文字 |
对于自定义 CSS，你也可以使用 %n 形式的调色板占位符，其中 n 是调色板的索引，它绑定了 %1, %2, ..., %n 占位符。它绑定了 %1， %2，...，%n占位符。
自定义HTML的工作原理是将模板字符串作为一个选项属性。在这个例子中，这是我们要使用的自定义HTML:
<a %x title='%text' class='%bClass'>%iconSvg</a>
要使用该模板，只需在插件代码中直接赋值 data-html 即可：
<script async src="//demo.chevereto.com/sdk/pup.js" data-url="https://demo.chevereto.com/upload" data-html="<a %x title='%text' class='%bClass'>%iconSvg</a>"></script>
自定义 CSS 的工作原理与自定义 HTML 完全相同，但它使用 data-button-css和 调色板占位符(%1，%2，...，%n)。在此示例中，这是我们要使用的自定义 CSS：
li.%cClass .%bClass{background:%1;color:%2;text-indent:unset;border-radius:3px;position:relative}li.%cClass a.%bClass:hover{background:%3;color:%4;border-color:%5}.%cClass .%bClass svg{font-size:15px;width:1em;height:1em;-webkit-transform:translate(-50%,-50%);-ms-transform:translate(-50%,-50%);transform:translate(-50%,-50%);position:absolute;left:50%;top:50%;fill:currentColor}
要使用该模板，只需在插件代码中直接赋值 data-css 即可：
<script async src="//demo.chevereto.com/sdk/pup.js" data-url="https://demo.chevereto.com/upload" data-css="li.%cClass .%bClass{background:%1;color:%2;text-indent:unset;border-radius:3px;position:relative}li.%cClass a.%bClass:hover{background:%3;color:%4;border-color:%5}.%cClass .%bClass svg{font-size:15px;width:1em;height:1em;-webkit-transform:translate(-50%,-50%);-ms-transform:translate(-50%,-50%);transform:translate(-50%,-50%);position:absolute;left:50%;top:50%;fill:currentColor};"></script>
重要提示： 对于自定义 HTML 和 CSS，请确保在使用引号时不要破坏语法。
# 手动绑定按钮
要手动绑定按钮，只需创建自己的按钮，请确保添加了 data-chevereto-pup-rigger 和 data-target 属性。以下是手动插入按钮的示例：
<div id="editor" contenteditable></div>
<button data-chevereto-pup-trigger data-target="#editor">Custom button</button>
手动插入的按钮获得相同的弹出对话框功能和绑定。但是，手动插入的按钮不会使用任何插件选项或模板。
# 核心功能
该插件功能非常简洁，并利用现代标准提供其核心功能。这些是塑造PUP核心的一些特征。
# 原生 JavaScript
PUP 是用现代 JavaScript 标准编写的，不需要任何外部库或服务器模块。代码大约是 18KB，而 gzip 应该只有 6KB 左右。使用 Google Close compiler (opens new window)] 缩小了源代码，但不会触及对象名称，因此您可以检查源代码并轻松理解代码。
它是异步工作的，所以不管你把插入代码放在哪里，它根本不会阻挡目标网站的加载。
# 智能负载与动态触发观察器
PUP 旨在观察 DOM，直到目标同级元素可用，一旦发生这种情况，它将启动其进程，并停止任何额外的 DOM 节点观察。对于动态生成的编辑器框，PUP 具有一附加的加载选项，用于观察定义选择器元素上的单击事件。任何单击该元素都将触发 PUP 的同级观察，一旦找到同级，它就会停止。这允许 PUP 在静态或动态编辑器框中工作。
由于一些动态编辑器框将只生成一次，然后存储为 DOM 节点（XenForo），而其他的编辑器框将总是被重新解析（Discourse，NodeBB），你可以指示 PUP 是否应该缓存观察到的触发绑定。XenForo、Discourse 和 NodeBB 厂商被配置为观察某些选择器，以防你想了解其工作原理。
# 闭包
源全部包装在 JavaScript 闭包中，这意味着内部变量不能调整。这旨在避免通过浏览器控制台漏洞或 DOM 操作进行劫持。这个闭包还保证了 PUP 处理的所有变量不会与目标网站上运行的任何脚本冲突。
# postMessage
PUP 使用 postMessage (opens new window) 接口与目标 Chevereto 网站保持主动通信。使用此 API 可以安全地处理选项和嵌入代码，该 API 限制发布消息的来源，最重要的是，PUP 会验证每条消息，以确保这些消息也没有篡改。PUP 将只收听来自目标 Chevereto 网站的消息。
# 多个实例
PUP 支持多个无限实例。你可以同时投出多个按钮，并且所有的实例 id 都使用 GUID算法 (opens new window) 来引用。
# 模板缓存
PUP 将缓存按钮模板，因此它不会不必要地重新处理模板占位符。这样即使在多个实例中也能获得超快的性能。
批量内容导入器 →