Annotorious.js 入门教程：图片注释工具

作者: 德育处主任 | 来源:发表于2023-08-25 06:52 被阅读0次

<div itemprop="articleBody" data-v-49c8f584="" style="font-weight: 400;"><h1 data-id="heading-0">本文简介</h1>
【今天我必须发一个封面！放文末！】

最近有工友问我前端怎么给图片做标注。使用 <code>Fabric.js</code> 或者 <code>Konva.js</code> 等库确实可以实现，但多少觉得有点大炮打蚊的感觉，好奇有没有专门做图片标注的工具呢？
在网上搜了一下发现 <code>Annotorious</code> 可以实现这个功能。<code>Annotorious</code> 提供了图片注释和标注功能，而且用法很简单。
<img src="https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/06a6050f6cf64ed69e50cf65c0a3694f~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="01.gif" loading="lazy">

本文分为【快速入门】和【API讲解】两部分。
【快速入门】部分包含 <code>Annotorious</code> 的安装、使用、导入导出的讲解。这几点应该是项目中比较核心的流程，给希望快速入门的工友提供一丢丢帮助。
【API讲解】这部分主要讲一下我认为比较常用的功能。注意：是“我认为”。

<h1 data-id="heading-1">快速入门</h1>
快速入门部分会讲解<code>Annotorious</code> 的安装、使用、导入和导出数据功能。

<h3 data-id="heading-2">安装 Annotorious</h3>
<h3 data-id="heading-3">CDN</h3>
<pre><code lang="html">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@recogito/annotorious@2.7.10/dist/annotorious.min.css">


<script src="https://cdn.jsdelivr.net/npm/@recogito/annotorious@2.7.10/dist/annotorious.min.js"></script>
</code></pre>
你可以把这两份文件下载到自己的项目里再引入。

<h3 data-id="heading-4">NPM</h3>
用以下命令安装 <code>Annotorious</code>
<pre><code lang="bash">npm install @recogito/annotorious
</code></pre>
然后在项目中引入
<pre><code lang="js">import { Annotorious } from '@recogito/annotorious'
import '@recogito/annotorious/dist/annotorious.min.css'
</code></pre>

<h2 data-id="heading-5">使用 annotorious</h2>
把 <code>Annotorious</code> 安装到项目后就可以使用了。
<code>Annotorious</code> 的用法很简单，只需做以下2步：
<ol>
<li>在html部分插入图片</li>
<li>初始化 <code>Annotorious</code>，并绑定图片元素（元素的ID或者元素本身）</li>
</ol>

<img src="https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f131b6e44fda4616b94f3e7aa96665d4~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="01.gif" loading="lazy">

<code>CDN</code> 和 <code>NPM</code> 在初始化时的用法稍微有点不同。
<h3 data-id="heading-6">CDN</h3>
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image' // 元素ID
})
</script>
</code></pre>
使用 <code>CDN</code> 的方式引入 <code>Annotorious</code>，在初始化时要 <code>Annotorious.init</code> 这样写。

<h3 data-id="heading-7">NPM</h3>
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
const anno = new Annotorious({
 image: document.getElementById('my-image') // 元素本身
})
</script>
</code></pre>
使用 <code>NPM</code> 的方式引入 <code>Annotorious</code> 在初始化时需要 <code>new Annotorious</code> 这样写。

注意：在 <code>Annotorious</code> 初始化代码最好放在你所使用的框架的页面加载完成后的生命周期函数里！

<h2 data-id="heading-8">导出数据 getAnnotations()</h2>
如果你需要将图片上的标注保存到服务器，就需要把数据导出。
所用到的方法是 <code>getAnnotations()</code>。
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/982c199adc8d48d596b37645dad65b05~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="02.png" loading="lazy">
<pre><code lang="html"><button onclick="save()">保存</button>
<img src="./44.jpg" id="img" />

<script>
 let anno = null

 onload = function() {
 anno = Annotorious.init({
 image: 'img'
 })
 }

 function save() {
 let res = anno.getAnnotations()
 console.log(res)
 }
</script>
</code></pre>

<h2 data-id="heading-9">导入数据 loadAnnotations(url)</h2>
<code>Annotorious</code> 可以通过 <code>loadAnnotations()</code> 方法加载数据。
<code>loadAnnotations(url)</code> 支持传入一个 <code>URL</code> 参数，这个 <code>URL</code> 所指的是数据文件地址。
比如我在本地创建一个 <code>data.json</code> 文件，文件内容是使用前面讲到的 <code>getAnnotations()</code> 方法导出的数据，我的数据内容如下：
<pre><code lang="json">[
 {
 "@context": "http://www.w3.org/ns/anno.jsonld",
 "type": "Annotation",
 "body": [
 {
 "type": "TextualBody",
 "value": "1",
 "purpose": "commenting"
 }
 ],
 "target": {
 "source": "http://127.0.0.1:5500/44.jpg",
 "selector": {
 "type": "FragmentSelector",
 "conformsTo": "http://www.w3.org/TR/media-frags/",
 "value": "xywh=pixel:100,100,500,300"
 }
 },
 "id": "#cabe2e71-b19f-4499-80c6-235882fd50ba"
 }
]
</code></pre>
在本地测试时，我使用了本地服务器把 <code>data.json</code> 管理起来，在浏览器可以通过 <code>http://127.0.0.1:5500/data.json</code> 访问到该文件。
然后再使用 <code>loadAnnotations(url)</code> 方法把数据渲染出来即可。
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c58e26d3625f4bce921b1093778bcdf4~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="04.png" loading="lazy">
<pre><code lang="html"><button onclick="load()">加载</button>
<img src="./44.jpg" id="img" />

<script>
let anno = null

onload = function() {
 anno = Annotorious.init({
 image: 'img'
 })
}

function load() {
 anno.loadAnnotations("http://127.0.0.1:5500/data.json")
}
</script>
</code></pre>
点击加载按钮后，图片上就会出现一个选框，点击选框可以看到数据已经成功加载出来。

<h2 data-id="heading-10">添加数据 addAnnotation()</h2>
但在实际项目中，后台不一定会给前端返回一个文件地址，后台可能会直接返回一个json数据。
这时候如果使用 <code>loadAnnotations()</code> 方法加载 <code>json</code> 数据是行不通的，要通过遍历读取数据中心的 <code>data</code> 里的数据，然后调用 <code>addAnnotation()</code> 方法将元素添加到页面。

我使用 <code>json-server</code> 简单的在本地搭建一个服务器给前端访问对应的资源，前端用 <code>axios</code> 请求资源。
<pre><code lang="html"><button onclick="load()">加载</button>
<img src="./44.jpg" id="img" />

<script>
let anno = null

onload = function() {
 anno = Annotorious.init({
 image: 'img'
 })
}

function load() {
 axios.get('http://localhost:3000/anno')
 .then(res => {
 res.data.data.forEach(item => {
 anno.addAnnotation(item)
 })
 })
}
</script>
</code></pre>

很久之前写过一篇 <a href="https://juejin.cn/post/7043424909472563208" target="_blank" title="https://juejin.cn/post/7043424909472563208">《『前端必备』本地数据接口 —— json-server 从入门到膨胀》</a> 文章介绍 <code>json-server</code> 的基础用法，有兴趣的工友可以去瞧瞧。

<h1 data-id="heading-11">API讲解</h1>
这部分主要讲一些我关注到的功能，如果想全面了解 <code>Annotorious</code> 可以查看<a href="https://link.juejin.cn/?target=https%3A%2F%2Fannotorious.github.io%2Fapi-docs%2Fannotorious%2F" target="_blank" title="https://annotorious.github.io/api-docs/annotorious/" ref="nofollow noopener noreferrer">文档</a>。

<h2 data-id="heading-12">汉化 locale</h2>
<code>Annotorious</code> 是根据浏览器的设置来确定使用哪种语言。
<img src="https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f8bd36ed5737475b9861f1faf874c45f~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="05.png" loading="lazy">

如果需要修改 <code>Annotorious</code> 使用的语言，可以在初始化时配置一下 <code>locale</code> 字段。
比如配置简体中文可以用 <code>zh-CN</code>，配置繁体中文可以用 <code>zh-TW</code>。
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/327def30e6684bf9b48c5321b0ac4083~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="06.png" loading="lazy">
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 locale: 'zh-CN' // 修改语言
})
</script>
</code></pre>

<h2 data-id="heading-13">自定义提示文本 messages</h2>
如果想自定义按钮或者输入框的提示文本可以配置 <code>messages</code> 。
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>

// 创建一个包含自定义消息的对象
var customMessages = {
 "Add a comment...": "评论评论",
 "Add a reply...": "回复两句",
 "Add tag...": "这是标签啊",
 "Cancel": "取消",
 "Close": "关闭",
 "Edit": "编辑~",
 "Delete": "删除❌",
 "Ok": "确定"
}

let anno = Annotorious.init({
 image: 'my-image',
 messages: customMessages // 自定义消息内容
})
</script>
</code></pre>
如果同时配置了 <code>locale</code> 和 <code>messages</code> ，会优先使用 <code>message</code> 的值。

<h2 data-id="heading-14">空注释 allowEmpty</h2>
默认情况下，如果框选后没输入标签或者评论就按确定是不会保存选框的。
<img src="https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/19c7e34362104175a7d103d276467c0f~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="07.gif" loading="lazy">
如果想保存空选框，可以将 <code>allowEmpty</code> 设置为 <code>true</code> 。
<img src="https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/43ec930580bc4f2296900e6c235eda21~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="08.gif" loading="lazy">
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 allowEmpty: true // 允许空注释
})
</script>
</code></pre>

<h2 data-id="heading-15">框选辅助线 crosshair</h2>
有些鼠标指针可能并不是那么标准，会影响你框选的准确性。
如果需要非常准确去框选，可以开启辅助线功能，只需将 <code>crosshair</code> 设置为 <code>true</code> 即可。
<img src="https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/eefc581019424d348eaebb9afd01d3e6~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="09.png" loading="lazy">
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 crosshair: true // 开启辅助线
})
</script>
</code></pre>

<h2 data-id="heading-16">只读 readOnly</h2>
如果不打算提供框选、添加和删除信息的操作给用户，可以将 <code>readOnly</code> 设置为 <code>true</code> 。
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 readOnly: true // 只读模式
})
</script>
</code></pre>

<h2 data-id="heading-17">禁止编辑 disableEditor</h2>
如果只需要画框框，不需要写注释，可以将 <code>disableEditor</code> 和 <code>allowEmpty</code> 同时设置为 <code>true</code>。
<img src="https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/db475118141646998de1ceebe7c52573~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="10.gif" loading="lazy">
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 allowEmpty: true, // 允许空注释
 disableEditor: true // 禁用编辑
})
</script>
</code></pre>
为什么要同时将 <code>allowEmpty</code> 设为 <code>true</code> ？
因为如果你不允许注释为空的话，当你点击空白处时选框就会消失。

<h2 data-id="heading-18">禁止选中选框 disableSelect</h2>
将 <code>disableSelect</code> 设置为 <code>true</code> 后，画布上的选框就无法再次选中了。
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 disableSelect: true // 禁止选中选框
})
</script>
</code></pre>
虽然还没想到有什么引用场景，但还是打算记录一下。

<h2 data-id="heading-19">手柄半径 handleRadius</h2>
箭头所指的就是手柄。
<img src="https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/1928839d192445039b1634a6c95f38b5~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="11.png" loading="lazy">
手柄的默认半径是6。如果需要修改手柄半径可以设置 <code>handleRadius</code> 属性。
<img src="https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ac53f1c8bf274e9094bd14c7884e9004~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="12.png" loading="lazy">
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 handleRadius: 20 // 设置手柄半径
})
</script>
</code></pre>

<h2 data-id="heading-20">自定义选框样式</h2>
<code>Annotorious</code> 的选框和编辑器都是可以使用 <code>css</code> 设置样式的。
选框部分使用了 <code>SVG</code> ，编辑器部分直接用了 <code>HTML</code> 元素。
对 <code>SVG</code> 不了解的工友可以阅读 <a href="https://juejin.cn/column/7113170709945253901" target="_blank" title="https://juejin.cn/column/7113170709945253901">《SVG专栏》</a>。

回到 <code>Annotorious</code> ，官方也有给出一个自定义样式的案例 <a href="https://link.juejin.cn/?target=https%3A%2F%2Fannotorious.github.io%2Fguides%2Fcustomizing-styles%2F" target="_blank" title="https://annotorious.github.io/guides/customizing-styles/" ref="nofollow noopener noreferrer">《Customizing Visual Appearance》</a>。
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b6f72b1e26b749b1b98cbfbbf127f1f2~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="13.png" loading="lazy">
<pre><code lang="html"><style>
 /* 选框 /
 / 隐藏外部形状-对于这种风格，我们只需要一个 /
 svg.a9s-annotationlayer .a9s-selection .a9s-outer, 
 svg.a9s-annotationlayer .a9s-annotation .a9s-outer {
 display:none;
 }
 svg.a9s-annotationlayer .a9s-handle .a9s-handle-outer {
 display:none;
 }

 / 虚线边框 /
 svg.a9s-annotationlayer .a9s-selection .a9s-inner,
 svg.a9s-annotationlayer .a9s-annotation .a9s-inner {
 stroke-width:4;
 stroke:white;
 stroke-dasharray:5;
 }

 / 选中时的填充色 /
 svg.a9s-annotationlayer .a9s-annotation.editable:hover .a9s-inner {
 fill:transparent;
 }

 / 手柄颜色 /
 svg.a9s-annotationlayer .a9s-handle .a9s-handle-inner {
 fill:white;
 stroke:white;
 }

 / 选中选框时，遮罩层颜色 /
 svg.a9s-annotationlayer .a9s-selection-mask {
 fill:rgba(0, 0, 0, 0.6);
 }

 / 编辑器 /
 / 容器 /
 .r6o-editor .r6o-editor-inner {
 box-sizing: border-box;
 padding: 10px;
 border-radius: 6px;
 background: #F4F2DE;
 }

 / 箭头 /
 .r6o-editor .r6o-arrow:after {
 background-color: #F4F2DE;
 }

 / 编辑器 /
 .r6o-widget.comment.editable,
 .r6o-widget.r6o-tag {
 background-color: #EEE3CB;
 }
 .r6o-widget.comment {
 background-color: #D7C0AE;
 }

 .r6o-editor .r6o-editor-inner .r6o-widget {
 border-bottom-color: #7C9D96;
 }

 .r6o-editor .r6o-editor-inner .r6o-widget.r6o-tag {
 border-bottom: none;
 }

 / 按钮 /
 .r6o-editor .r6o-btn {
 border-radius: 100px;
 background-color: #7C9D96;
 border-color: #7C9D96;
 color: #fff;
 }

 / 线框按钮 */
 .r6o-editor .r6o-btn.outline {
 color: #7C9D96;
 background-color: transparent;
 }
</style>

<img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 locale: 'zh-CN' // 修改语言
})
</script>
</code></pre>

上面这份代码选框的样式是从 <code>Annotorious</code> 官网教程搬过来的。
编辑器的样式我随便配了一下，工友们也可以打开浏览器控制台看 <code>Elements</code> 面板的 <code>HTML</code> 代码，根据结构去修改样式即可。

<h2 data-id="heading-21">筛选功能</h2>
输入时需要快速添加预选项时，可以这样配置：
<img src="https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e054b682049c48e8b1a88a65db1e3a6c~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="14.png" loading="lazy">
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image',
 widgets: [
 'COMMENT',
 { widget: 'TAG', vocabulary: [ '雷猴', '鲨鱼辣椒', '蝎子莱莱'] }
 ]
})
</script>
</code></pre>

<h2 data-id="heading-22">多边形选框</h2>
使用 <code>setDrawingTool(toolName)</code> 方法可以设置不同的绘制工具。
如果需要讲选框设置成多边形，可以传入 <code>'polygon'</code>。
<img src="https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4a428b4853ed43eebc1c56d1fe91a887~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="15.png" loading="lazy">
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image'
})

anno.setDrawingTool("polygon")
</script>
</code></pre>

想要知道当前有哪些绘图工具，可以使用 <code>anno.listDrawingTools()</code> 方法查看
<img src="https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/83c04c98e38a49849e87648979e8400a~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="16.png" loading="lazy">
<pre><code lang="html"><img src="./img.jpg" id="my-image" />

<script>
let anno = Annotorious.init({
 image: 'my-image'
})

const toolNames = anno.listDrawingTools()
console.log(toolNames)
</script>
</code></pre>

<h2 data-id="heading-23">其他</h2>
除了上面介绍到的 <code>API</code> 外，<code>Annotorious</code> 还有很多玩法的，比如删除指定注释、清空所有注释等。
详情请看 <a href="https://link.juejin.cn/?target=https%3A%2F%2Fannotorious.github.io%2Fapi-docs%2Fannotorious%2F" target="_blank" title="https://annotorious.github.io/api-docs/annotorious/" ref="nofollow noopener noreferrer">《annotorious API文档》</a>

<h1 data-id="heading-24">插件</h1>
<code>Annotorious</code> 也有一些好玩的插件，有兴趣的可以看看 <a href="https://link.juejin.cn/?target=https%3A%2F%2Fannotorious.github.io%2Fplugins%2F" target="_blank" title="https://annotorious.github.io/plugins/" ref="nofollow noopener noreferrer">《Annotorious 插件推荐》</a>。

<h1 data-id="heading-25">推荐阅读</h1>
👍<a href="https://juejin.cn/post/7238431802299138105" target="_blank" title="https://juejin.cn/post/7238431802299138105">《提升日期处理效率：day.js 实战经验分享》</a>
👍<a href="https://juejin.cn/post/7243357900939690042" target="_blank" title="https://juejin.cn/post/7243357900939690042">《OpenLayers.js 入门教程：打造互动地图的入门指南》</a>
👍<a href="https://juejin.cn/post/7221550123193811002" target="_blank" title="https://juejin.cn/post/7221550123193811002">《物理世界的互动之旅：Matter.js入门指南》</a>
👍<a href="https://juejin.cn/post/7173451612654927908" target="_blank" title="https://juejin.cn/post/7173451612654927908">《p5.js 光速入门》</a>
👍<a href="https://juejin.cn/post/7215100383599870010" target="_blank" title="https://juejin.cn/post/7215100383599870010">《眨个眼就学会了Pixi.js》</a>
👍<a href="https://juejin.cn/post/7026941253845516324" target="_blank" title="https://juejin.cn/post/7026941253845516324">《Fabric.js 从入门到膨胀》</a>

点赞 + 关注 + 收藏 = 学会了
<img src="https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7e789303aa77493db3ac9b9d92963520~tplv-k3u1fbpfcp-zoom-in-crop-mark:1512:0:0:0.awebp?" alt="640.gif" loading="lazy"></div><blockquote>本文使用 <a href="https://www.jianshu.com/p/5709df6fb58d" class="internal">文章同步助手</a> 同步</blockquote>

Annotorious.js 入门教程：图片注释工具

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读