一. 开发步骤
1. 文件结构
index.json 插件核心配置,不可改名index.html 插件的入口文件,不可改名icon.png 插件图标,不可改名
2. 测试插件附件
📎附件 (13.5 KB)
3. index.json文件解读
{
"code": "test", // 插件编码,需要唯一,入驻官方的时候不可和已有的重复
"name": "插件测试", // 插件名称
"version": "1.0.0", // 插件版本,判断插件是否需要更新的条件
"author": "阿范", // 作者
"firstCat": "app", // 一级归类,app表示程序 game表示游戏
"secondCat": "文件增强", // 二级归类,参见应用商店二级目录,必须使用有的,否则分类下找不到该插件
"imgPath": "apps/test/icon.png", // 插件图标
"descr": "插件测试", // 插件描述
"screenShots": "[]", // 插件截图
"effect": "插件测试", // 插件解说
"rightMenuAddAll": [
{"ext": "test","icon": "apps/test/icon.png", "expAction": "list","name": "测试列表"}
], // 批量右键功能,多个相同格式的文件,选中后右键会出现该选项
"rightMenuOpenWith": [
{"ext": "test","icon": "apps/test/icon.png", "expAction": "open","name": "测试打开"}
], // 单一右键功能,符合格式的单个文件选中后右键会出现该选项
"rightMenuNew": [
{"ext": "test","icon": "apps/test/icon.png", "expAction": "new","name": "测试 文件"}
], // 右键新建功能,右键新建会出现该选项
"updateLog":"", // 更新日志
"singleton":1, // 1单例模式 其他非单例模式,单例模式只允许打开一个窗口
"exts": {
"test,test1":"apps/test/icon.png"
} // 文件图标映射,用于扩充文件的预览图标
}
4. 快速上手
可先通过下载上面的测试插件进行解读,详细步骤如下：
- 初始化页面：通过
js/init.js链接webos的element-ui(目前采用2.2.13版本,Vue采用版本3)，图1中是index.html文件参数from表示使用哪一套ui，目前系统仅内置了element-ui，plugins表示加载哪些插件，多个采用逗号分割，图2中是js/init.js文件红框部分是推荐修改的，其他部分不建议动。
- 初始化页面：通过
Vue.app方法进行初始化页面，默认不传el的话绑定到<div id="app"></div>，其他和常规开发Vue页面是一样的，参见下图。图3中蓝框表示点击页面的时候能置顶窗口推荐保留，否则点击页面体的时候无法进行窗口置顶，红框是仅当有右键新建文件的时候进行处理的，其中Blob则是文件的内容，此处采用空内容。
<script src="js/init.js?from=element&plugins=test"></script>
- 当前插件的plugins使用：上面图1中有一行：
config.plugins.test = [
{js:rootPath+"/apps/test/js/test.js"}
];
这两个组合起来会让框架加载该js,可通过该js提供相关入口进行操作,参见图3中的toClick方法,使用了test.js中的mytest全局变量。
二. API文档
1. 读取文件
执行 await webos.fileSystem.zl("{uio:1}/1.txt",1,true,fileName)
// 返回 http://localhost:8088/webos/file/5cecf1ea842e42349bb41c53ab19d0e2/cache.data
| 参数顺序 |
类型 |
说明 |
| 参数1 |
字符串 |
文件路径 |
| 参数2 |
整型 |
1. 下载内容(使用重定向) 2. 前端获取内容(支持的使用重定向,不支持的使用中转) 3. 获取预览图(三方重定向,本地走流) 4. 直接流,固定中转,不重定向,合适第三方不支持重定向的系统 |
| 参数3 |
逻辑型 |
true 不带http://网址 false 带http://网址 |
| 参数4 |
文件名 |
文件名,不传默认为cache.data |
::: tip
此地址仅有8小时有效期,不可长期使用
:::
2. 写入文件(小文件)
var param = {
file: new Blob([str]),
name: "文件.txt",
parentPath: "{uio:1}/ss"
}
var fileId = await webos.fileSystem.uploadSmallFile(param);
| 参数顺序 |
类型 |
说明 |
| 参数1 |
对象 |
file 是一个 blob 对象, name 是文件名, parentPath 是父级路径 |
::: tip
此方法是完整传,不采用分片传输,走中转方案,推荐小文件使用
:::
3. 写入文件(大文件)
// 分片上传
var param = {
file: fp, // 文件分片,Blob或者File类型,大小不限,建议10M
parentPath: "{uio:1}/ss", // 父级目录
fpMd5: "", // 分片MD5用于校验分片完整性
md5: "", // 文件MD5用于校验文件完整性
fpIndex: 0, // 分片序号,从0开始
fpCount: 9 // 分片数量
}
var flag = await webos.fileSystem.uploadBigFileUpload(param);
// 返回逻辑型 true 表示上传成功 false 表示上传失败,请务必按照顺序上传,不可同时传
// 所有分片上传完毕后调用下面方法
// 检查上传结果
var param = {
name: "文件名.txt",
parentPath: "{uio:1}/ss", // 父级目录
md5: "" // 文件MD5用于校验文件完整性
}
var data = await webos.fileSystem.uploadBigFileCheck(param);
// 返回对象
// data.status 为 1 等待上传 2 正在上传 3 上传成功 4 上传失败
// data.sd 上传速度 KB/S
// data.error 上传失败的原因
// data.jd 已上传的字节数
// 当检查到 3 或者 4 也就是上传成功或者上传失败的时候调用下面方法
// 清除上传标记
var param = {
name: "文件名.txt",
parentPath: "{uio:1}/ss", // 父级目录
md5: "", // 文件MD5用于校验文件完整性
clear: true
}
var data = await webos.fileSystem.uploadBigFileCheck(param);
// 如果不调用清除标记,可能在两小时无法上传同一个md5文件
::: warning
注意: 分片上传请务必按照顺序上传,需要一个分片上传完毕才能上传下一个,所有分片上传完毕再持续调用检查上传结果,分片上传属于浏览器到服务器上传的步骤,检查结果相当于从服务器上传到第三方(如果是本地就是移动文件)
:::
4. 读写持久化数据
// 写入持久化数据(数组)
await webos.softUserData.syncList("abc_history_list", sz)
// 写入持久化数据(map)
await webos.softUserData.syncObject("abc_id1", obj)
// 写入持久化数据(字符串)
await webos.softUserData.syncData("abc_remark", str)
// 读取持久化数据(数组)
var sz = await webos.softUserData.syncList("abc_history_list")
// 读取持久化数据(map)
var obj = await webos.softUserData.syncObject("abc_id1")
// 读取持久化数据(字符串)
var str = await webos.softUserData.syncData("abc_remark", str)
| 参数顺序 |
类型 |
说明 |
| 参数1 |
字符串 |
需要读写的 key |
| 参数2 |
数组, 对象, 字符串 |
存在表示写入, 不存在表示读取 |
5. 置顶窗口
webos.inface.toTopWin(window);
6. 关闭窗口
webos.inface.closeCurrentWin(window);
7. 设置极简窗口
webos.inface.setWinSimple(window, flag);
| 参数顺序 |
类型 |
说明 |
| 参数2 |
逻辑型 |
true 为设置为极简窗口 false 为非极简窗口 |
8. 设置窗口大小
webos.inface.winChangeSize(window, width, height);
| 参数顺序 |
类型 |
说明 |
| 参数2 |
整型 |
宽度 |
| 参数3 |
整型 |
高度 |
9. 文件目录选择器
webos.inface.selectFileExt("*", function (sz) {
if(sz.length != 1){
webos.message.error("请选择一个文件后重试");
return false;
}
var file = sz[0];
var item = {name: file.name, path: file.path, ext: file.ext};
console.log(item)
return true;
}, false);
| 参数顺序 |
类型 |
说明 |
| 参数1 |
字符串 |
接受文件格式, * 表示全部, folder 表示文件夹, 其他表示文件格式, 多个逗号分割 |
| 参数2 |
函数 |
返回 true 会关闭选择器, 返回 false 不会关闭选择器 |
| 参数3 |
逻辑型 |
true 为允许多选, false 为限制单选 |
10. 跨域请求
webos.request.proxy(
url, // 跨域网址 如 https://www.baidu.com
method, // 方法名, 默认 GET
headerMap, // 请求头 map 如 {"referer": "https://www.baidu.com"}
data, // 如果是 FormData 类型, 则直接提交, 如果是 Blob 类型则组装整 FormData 并且 key 为 file, 其他情况都视为 Obj, 采用 json 提交, 自动添加 application/json
cdx, // 为空表示不自动重定向, 否则自动重定向
resHeaderMap, // 读取返回的 header, 例如传 {"set-cookie": "my-set-cookie"} 则可以通过 my-set-cookie 的值获取原本 set-cookie 的值
progress, // 进度条 例如 function(loaded, total, type){} loaded 是已提交内容, total 是总共大小, type 为 1 是上传 2 是下载
responseType, // 同 xhr.responseType
clear // 是否采用新客户端, 为空则采用默认客户端, 否则新建 HttpClient
);
// 此方法返回一个 Promise<XMLHttpRequest>
11. 窗口调用(仅限桌面模式)
- 携带文件打开其他插件
文件信息为 file = {path: "{uio:1}/1.xlsx", name: "1.xlsx", ext: "xlsx"}
webos.inface.openSoft("apps/wps/index.html?action=openwith&path=" + encodeURIComponent(file.path) + "&fname=" + encodeURIComponent(file.name) + "&ext=" + encodeURIComponent(file.ext) + "&expAction=open");
- 直接打开其他插件
webos.inface.openSoft("apps/birdpaper/index.html");
- 打开网址
webos.inface.openSoft("https://cn.bing.com");
12. 接收webos的文件拖放
window.addEventListener("message", async function (e){
let data = e.data;
if(data.action == "addOpenFiles"){
//[{ext, name, path, type}]
const openOneFile = async function (file) {
// 你的文件处理代码
}
for (let i = 0; i < data.files.length; i++) {
openOneFile(data.files[i]);
}
}
});
13. 接收webos的主题反馈
window.addEventListener("message", async function (e){
let data = e.data;
if(data.action == "themeChange"){
// 你的主题处理代码
}
});