资源工坊

工作台小组件开发 ​

开发环境 ​

node 18+

下载开发模板 ​

小组件开发模板

Usage ​

首先进入WPS开放平台 > 应用能力 > 工作台小组件能力配置 > 创建小组件

复制block_type_id

进入小组件模板根目录config/evn.json，粘贴复制的block_type_id

依次执行

yarn

git init

git add .

git commit -m "xxx"

打包会带上commit信息用于确认包版本，所以打包前务必执行commit

完成上述步骤后，执行 yarn build ，会在根目录下生成bundle文件夹和androidBundleCommonInfo.json和iosBundleCommonInfo.json，后两个json是用来映射基础包依赖关系的，不要动。

bundle文件夹下common为基础包，忽略即可。剩下三个包即是需要上传的包。

回到WPS开放平台刚刚复制block_type_id的小组件页面，点击创建版本，按提示上传三端包即可。

如何开发小组件 ​

小组件的实现是完全依赖于react-native的，PC是通过react-native-web编译而成，所以一切遵循react-native&react的框架规范和语法逻辑，相关问题请翻阅React Native官方文档

PC端开发 ​

  1. 执行 yarn dev:web，将在项目目录下的 dist 文件夹输出小组件产物。
  2. 打开金山协作调试模式，在 localStorage 中新增 workspace_debug_comp 参数，name 为 block_type_id，url可以为任何端内能正常访问加载的 url（同源或者白名单），例如：https://woa.wps.cn/debugwidget/block.js。（仅新增小组件开发调试需配置，开发已上线小组件直接代理接口返回的 packages 中的 url 即可）
  3. 在 localStorage 配置 workspace_debug_nocache 为 true，可以让客户端工作台不读取缓存，每次加载都从 url 获取最新数据。

  1. 本地启动一个服务，推荐VSCode插件Live Server

安装后点击go live，默认端口应该是5500，也可以更改成其他端口，具体使用方式看插件文档。

因为本地启动的服务是无法直接在客户端中加载渲染的，所以接下来要做的事就是把localstorage中配置的能够正常访问的url代理到本地服务的ip:port上去。（例如host+nginx、whistle等等）

下面是用whistle的方式：

  1. 开启金山协作网络代理，设置=>通用设置=>网络代理（去设置），代理服务器为whistle服务。

  1. 在代理中将 localstorage中配置的url（https://woa.wps.cn/debugwidget/block.js）请求指向本地产出的小组件js后打开工作台即可看到小组件成功注册

小组件的调试信息输出在工作台所在的webview，请先在控制台执行以下代码打开工作台调试工具

document.querySelector('#webview-portal-workspace').openDevTools()

小组件代码改动后要看最新改动的效果，可选中工作台的调试工具（mac是cmd+r，windows是ctrl+r）单独刷新工作台。

移动端开发 ​

敬请期待

props属性 ​

以下为几个所有组件都会接收到的数据信息

属性名数据类型含义
blockidstring当前组件的id
heightnumber小组件高度高度（如存在标题含去标题高度）
isPadStyleboolean是否是移动端pad布局
isMobileboolean是否是编辑器移动端（用于区分web环境，移动端没有此字段，仅用于编辑器适配）
showHeaderboolean小组件是否显示标题的状态
transparencynumber小组件透明度
langstring当前语言环境：zh-CN 简体中文、zh-TW 繁体中文、en-US 英语、th-TH 泰语、ja-JP 日语

API ​

当小组件需要主动调用客户端提供的能力时，就需要用到客户端向react-native注册的api方法。

react-native中的NativeModules下存在对象WOARCTBridgeModule，上面有挂载小组件所支持的api，可以通过调用相关api实现对应功能，随着版本的迭代可能会新增api，所以调用前请进行判空操作，以防较早版本客户端没有当前api而出现报错阻塞渲染的情况。

javascript
import { NativeModules } from 'react-native'
const ksxz = NativeModules.WOARCTBridgeModule
ksxz.xxx...

login ​

获取临时登录凭证，参数为组件的blockId。会通过props传入，如果是初次开发可以先上传模板在预览编辑器中添加组件获取blockId临时写死在组件中进行mock。

方法名参数返回值
loginblockId: stringJSON.Stringify({ code: 0, data: { code: 'xxxxxxxxxxx' }, msg: 'success' })

javascript
import { NativeModules } from 'react-native'
const ksxz = NativeModules.WOARCTBridgeModule

const App = (props) => {
  const { blockId } = props
  useEffect(() => {
    login()
  }, [])

  const login = async () => {
    const res = await ksxz.login(blockId)
    const { code, data, msg } = JSON.parse(res)
    ...
  }
  ...
}

request ​

发起http请求，存在于gateway网关当中的域名传后缀即可，通过读取serviceName字段进行拼接域名前缀。传值需要stringify序列化，返回值同样是stringify后的data。

非gateway网关服务内置域名推荐使用react-native官方内置fetch方法。

方法名参数返回值
request同axiosPromise<string>
javascript
NativeModules.WOARCTBridgeModule.request(`api/v1?block_id=${blockId}`, {
  method: 'GET',
  serviceName: 'woa',
})

NativeModules.WOARCTBridgeModule.request(`api/v1/`, {
  method: 'post',
  serviceName: 'woa',
  body: JSON.stringify(data),
})

getStyleSetting ​

获取当前客户端样式相关设置，包含字号和主题色

方法名参数返回值描述
getStyleSettingvoidJSON.stringify({ fontScaleLevel: number, colorTheme: 'light' | 'dark' })fontScaleLevel：字体缩放级别，PC端取值范围0-3，mobile取值范围0-5。colorTheme：主题色，'light'为浅色模式，'dark'为深色模式。

使用示例：

javascript
NativeModules.WOARCTBridgeModule.getStyleSetting()

getServiceUrl ​

获取对应服务的域名

方法名参数返回值
getServiceUrlserviceName: stringurl: string

使用示例：

javascript
NativeModules.WOARCTBridgeModule.getServiceUrl('woa')

打开deeplink

方法名参数返回值
openDeeplinkdeeplink: stringvoid

使用示例：

javascript
NativeModules.WOARCTBridgeModule.openDeeplink(`ksoxz://xz.wps.cn/webapp?app_id=${appid}`)

onDragApp ​

仅移动端支持，拖拽事件，通知移动端当前拖拽状态，屏蔽移动端本身的部分事件。

方法名参数返回值
onDragAppstatus: 0 | 1 | 2void

参数说明：

0: 开始拖拽，屏蔽移动端页面滑屏

1: 拖拽中，通知移动端当前是拖拽事件，非长按，关闭长按相关菜单

2: 结束拖拽，恢复移动端页面滑屏

使用示例：

javascript
NativeModules.WOARCTBridgeModule.onDragApp(0)

事件通信 ​

当客户端需要主动向小组件推送某些更新时，就需要小组件监听端推送过来的事件。

react-native中的NativeEventEmitter可以用来监听端触发的事件，客户端向NativeModules中注册了WOARCTCustomEventEmitter自定义事件触发器，构建对象的时候传入即可

javascript
import { NativeModules, NativeEventEmitter } from 'react-native'

const eventEmitter = new NativeEventEmitter(NativeModules.WOARCTCustomEventEmitter)

useEffect(() => {
  let stylesListener = eventEmitter.addListener('app_style_setting_change', (styleSettingStr: string) => {
    setStyleSetting(JSON.parse(styleSettingStr))
  })
  return () => {
    // 养成销毁监听的好习惯
    if (stylesListener) {
      stylesListener.remove()
    }
  }
}, [])

事件类型 ​

事件名回调函数参数说明
app_style_setting_changestyleSettingStr: stringgetStyleSetting的主动推送版，一般在初始化时调用getStyleSetting获取初始值，然后监听该事件进行响应客户端操作的变更。回调函数参数同getStyleSetting。
$any针对特定组件推送的事件，事件名为组件的实际blockId，回调函数参数取决于业务方需要传达的内容。

注意事项 ​

  • 小组件模板里根目录下common.ts文件中引入的依赖包版本不能更新，否则可能会对不上端内依赖的基础包版本依赖，导致渲染失败报错。