uni_modules插件整理记录

发表于 分类于 Waline：

图片编辑组件功能整理得差不多以后，我又把它放进了 uni_modules，顺手记录一下从业务组件整理成插件时需要注意的地方

一开始图片编辑只是项目里的一个普通组件。

路径大概是：

1
components/csImageEditor/index.vue

后面功能慢慢多了，拖拽、缩放、旋转、镜像、保存、路径转换都放进来了。

这时候如果还只是当成业务组件用，就不太方便复用。

所以我把它整理成了 uni_modules 插件。

插件市场地址：

cs-ImageEditor 插件市场地址

为什么要整理成插件

普通组件当然也能用。

但是如果以后别的项目也要用，就会遇到几个问题：

  1. 不知道要复制哪些文件
  2. 不知道组件有哪些参数
  3. 不知道需要监听什么事件
  4. 不知道哪些方法要通过 ref 调用
  5. 不知道兼容哪些平台
  6. 不知道版本改了什么

所以插件化不只是换一个目录。

更重要的是把使用方式、接口说明和版本记录整理清楚。

目录结构

整理后的目录大概是这样：

1
2
3
4
5
6
7
8
9
10
uni_modules
  cs-ImageEditor
    components
      cs-ImageEditor
        cs-ImageEditor.vue
        image-tools.js
        html2canvas.min.js
    package.json
    readme.md
    changelog.md

真正的组件放在：

1
uni_modules/cs-ImageEditor/components/cs-ImageEditor/cs-ImageEditor.vue

工具函数和依赖文件也跟组件放在一起。

这样使用方导入插件后，不需要再去项目其他目录找依赖。

package.json

插件的 package.json 主要用来描述插件信息。

比如：

1
2
3
4
5
6
{
  "id": "cs-ImageEditor",
  "displayName": "cs-ImageEditor",
  "version": "1.2.0",
  "description": "uniapp图片编辑插件"
}

这里的 version 比较重要。

后面改功能、修兼容问题，都应该同步更新版本。

不然使用方不知道自己当前用的是哪个版本。

平台说明

这个组件里面涉及图片路径、保存图片、触摸事件、renderjs，所以平台兼容性一定要说明。

package.json 里面可以写平台支持情况。

比如 Vue2、Vue3，App，H5，小程序这些。

但是实际写插件说明时，我觉得还要补充一句：

1
不同端图片路径和保存相册能力不同，使用时需要按平台测试。

因为这种图片处理组件，很难只靠配置表就保证所有端完全一样。

props设计

组件对外暴露的参数不要太多，但是要覆盖常用场景。

这次整理了这些 props：

1
2
3
4
5
6
7
imageSrc
boxWidth
boxHeight
opacity
circleDiameter
showMasker
showRotateIcon

imageSrc 是图片来源。

boxWidth 和 boxHeight 控制编辑区域大小。

opacity 控制遮罩透明度。

circleDiameter 控制圆形裁剪区域。

showMasker 和 showRotateIcon 控制是否显示遮罩和旋转图标。

这些参数都是使用方真正可能会改的。

如果只是组件内部使用的状态，就不要暴露出去。

methods设计

组件内部逻辑比较多，但是对外方法应该尽量简单。

这次对外主要是：

1
2
3
4
init()
rotateCounterClockwise()
mirrorImage()
saveImage()

页面使用时通过 ref 调用：

1
2
3
this.$refs.csImageEditor.rotateCounterClockwise()
this.$refs.csImageEditor.mirrorImage()
this.$refs.csImageEditor.saveImage()

这样外部页面不用关心内部怎么计算 transform。

只需要知道我要旋转、我要镜像、我要保存。

events设计

保存图片是一个异步过程。

组件内部要先截图，再转 base64，再转临时路径。

所以最终结果用事件返回：

1
@sendUrl="updata"

返回数据：

1
2
3
4
{
  base64: url,
  filePath: path
}

这样组件不直接帮业务页面保存相册，而是把结果交给使用方。

我觉得这里不要把业务动作写死在组件里。

因为有的页面可能要保存到相册，有的页面可能要上传到服务器，有的页面可能只是预览。

readme要写什么

插件的 readme.md 不能只写一句介绍。

至少要包括：

  1. 插件介绍
  2. 安装方式
  3. 基础使用示例
  4. props 表格
  5. events 表格
  6. methods 表格
  7. 平台兼容说明
  8. 权限说明
  9. 注意事项

尤其是图片保存这种功能，权限说明要写清楚。

比如保存相册时，App 端和 iOS 端可能都要申请对应权限。

changelog

changelog.md 也要维护。

这次记录大概是：

1
2
3
1.0.0 初始版本
1.1.0 小程序兼容
1.2.0 适配微信小程序最新基座

更新日志看起来不起眼，但是插件一旦被别的项目引用，它就很有用。

遇到问题时，至少能知道某个兼容处理是在哪个版本加的。

上传到插件市场

整理成 uni_modules 以后，如果要上传到 uni-app 插件市场，最好用 HBuilderX 来操作。

官方对 uni_modules 做了右键菜单支持，不需要自己手动打压缩包上传。

大概流程是：

  1. 登录 HBuilderX 的 DCloud 账号
  2. 打开插件所在项目
  3. 找到 uni_modules/cs-ImageEditor
  4. 右键插件目录
  5. 选择 发布到插件市场
  6. 按窗口提示填写插件信息
  7. 选择是否上传当前项目作为示例工程
  8. 提交审核或发布

如果后面要更新新版本，也是同样操作。

在插件目录上右键，再选择 发布到插件市场，它会按新版本上传。

如果是第一次发布插件，流程一般是：

  1. 先把组件整理到 uni_modules 目录
  2. 补全插件根目录下的 package.json
  3. 写好 readme.md
  4. 写好 changelog.md
  5. 用 HBuilderX 打开这个项目
  6. 登录 DCloud 账号
  7. 右键插件目录，选择 发布到插件市场
  8. 按页面提示填写插件分类、关键词、兼容平台、开源协议等信息
  9. 确认发布，等待插件市场处理

如果是已经发布过的插件，后面更新版本时，流程也差不多：

  1. 修改插件代码
  2. 修改 package.json 里面的 version
  3. 修改 changelog.md，说明本次更新内容
  4. 用 HBuilderX 打开项目
  5. 右键插件目录，选择 更新插件市场
  6. 确认本次发布版本
  7. 提交更新

这里要注意，插件市场发布不是只上传一个 .vue 文件。

它需要的是完整的插件目录。

也就是：

1
uni_modules/插件ID

比如这个图片编辑插件，对应的目录就是：

1
uni_modules/cs-ImageEditor

所以发布的时候，右键的应该是这个插件目录，而不是项目根目录。

如果右键的是项目根目录，那就不是发布插件了。

发布前的准备

正式发布前，建议先检查这几项：

  1. package.json 里的 id 是否和插件目录一致
  2. version 是否已经递增
  3. displayName 和 description 是否能说明插件用途
  4. keywords 是否补充完整
  5. readme.md 是否有完整使用示例
  6. changelog.md 是否写了本次更新内容
  7. 示例页面是否能正常运行
  8. 组件引用路径是否都是插件目录内的相对路径
  9. 插件目录里有没有误放项目级文件

版本号一定要注意。

如果只是改了文档，可以小版本更新。

如果改了组件功能或者兼容性，就应该把版本号也同步改掉。

比如：

1
1.2.0 -> 1.3.0

然后在 changelog.md 里面写清楚这次改了什么。

发布时要填什么

HBuilderX 发布到插件市场时，一般会让你确认一些信息。

常见的有：

  1. 插件名称
  2. 插件分类
  3. 插件简介
  4. 关键词
  5. 版本号
  6. 兼容平台
  7. 是否开源
  8. 是否免费
  9. 更新日志
  10. 是否上传示例工程

这些信息最好提前在 package.json 和 readme.md 里面整理好。

不然发布的时候临时填，很容易漏东西。

示例工程要不要上传

如果插件只是一个普通 UI 组件，不上传示例工程问题不大。

但是图片编辑这种插件，我建议上传示例工程。

因为它不是只看一个组件标签就能明白怎么用。

使用者还需要知道：

  1. 怎么选择图片
  2. 怎么调用 init
  3. 怎么调用旋转和镜像
  4. 怎么触发保存
  5. 怎么监听 sendUrl
  6. 怎么调用 uni.saveImageToPhotosAlbum

所以最好准备一个最小示例页面。

示例不需要复杂，能跑通完整流程就行。

发布后的更新

插件发布以后，如果只是改标题、简介、关键词、readme 这些基础信息，可以在 HBuilderX 里面选择 修改插件基本信息。

如果代码有变化，就应该走更新插件流程。

每次更新最好都做三件事：

  1. 改版本号
  2. 写更新日志
  3. 本地跑一遍示例

这样别人看到插件市场的版本记录时，也能知道每个版本大概解决了什么问题。

上传前要检查什么

上传前我觉得至少要检查这些东西。

首先是 package.json。

插件市场会读取这里面的基础信息：

1
2
3
4
5
6
{
  "id": "cs-ImageEditor",
  "displayName": "cs-ImageEditor",
  "version": "1.2.0",
  "description": "uniapp图片编辑插件"
}

id 最好稳定下来，不要后面随便改。

version 每次发布新版本都要递增。

description 和 keywords 要能说明插件是干什么的。

然后是 readme.md。

插件市场详情页主要就是给别人看这个文档。

所以 readme 里面要把使用方式写清楚。

至少要有：

  1. 插件介绍
  2. 基础使用代码
  3. props 说明
  4. events 说明
  5. methods 说明
  6. 权限说明
  7. 注意事项

再然后是 changelog.md。

HBuilderX 发布窗口里填写的更新日志，会同步到插件根目录的 changelog.md。

所以不要把更新日志当成可有可无。

哪些文件不要放进插件目录

插件目录里面不要放项目级文件。

比如：

1
2
3
4
5
pages.json
App.vue
main.js
manifest.json
uni.scss

这些文件属于项目配置，不应该放进插件目录。

如果插件使用者需要改这些文件，比如要加权限、加页面、改 manifest 配置，应该写在 readme.md 里面提醒。

还有两个目录也要注意：

1
2
unpackage
node_modules

unpackage 是构建产物，不应该跟着插件上传。

node_modules 一般也不要放进去。

如果依赖的是其他 uni_modules 插件，可以在 package.json 的 uni_modules.dependencies 里面声明。

如果依赖的是 npm 包，再按 npm 依赖的方式处理。

示例工程

发布插件的时候，可以选择上传当前项目作为示例工程。

这个图片编辑插件我觉得最好带示例工程。

因为它不是一个纯展示组件，使用者需要知道完整流程：

1
2
3
4
5
6
7
选择图片
调用 init
调用 rotateCounterClockwise
调用 mirrorImage
调用 saveImage
监听 sendUrl
保存到相册

如果只有组件文档，没有示例页面，别人第一次接入的时候很容易不知道怎么触发保存。

所以示例工程里可以保留一个简单页面：

1
pages/index/index.vue

里面放选择图片、旋转、镜像、保存这几个按钮就够了。

示例工程不需要复杂，越直接越好。

修改插件信息

插件发布以后，如果只是想改插件名称、描述、关键词、readme 这些基础信息，不一定要重新发一个功能版本。

HBuilderX 里面可以在插件目录右键，选择 修改插件基本信息。

这个适合修正文档、补充说明、改关键词。

如果是代码变了，那就应该正常升级版本再发布。

发布时的注意点

图片编辑这种插件，我觉得发布时要特别写清楚几个点：

  1. 保存相册需要权限
  2. 网络图片要注意跨域
  3. App、小程序、H5 的路径处理方式不同
  4. renderjs + html2canvas 主要用于视图层截图
  5. 插件虽然支持多端，但实际项目最好按目标端测试一遍

这些话写在文档里，能减少很多使用者的疑问。

尤其是跨端图片处理，没有绝对的一次写完所有端都完全一样。

插件作者最好把自己遇到的问题提前写出来。

总结

从业务组件整理成 uni_modules 插件，不只是改目录。

真正要整理的是：

  1. 组件接口
  2. 使用文档
  3. 平台兼容
  4. 权限说明
  5. 版本记录
  6. 示例代码

这次图片编辑组件本身就有跨端问题，所以整理成插件时，更要把这些坑写在文档里。

否则别人导入以后，只看到组件能跑，却不知道为什么有些端需要特殊处理。

以上就是我对 uni_modules 插件整理的记录，如有错误，欢迎大佬指出。

-------------本文结束感谢您的阅读-------------