伙伴云表格应用 JS-SDK (英文版)

构建基于伙伴云表格的应用

引入
初始化
SDK API
Channel API
Client(应用端) API
Message API

引入

// ES6
import {client, host} from 'huoban-app-sdk'
// or
import * as HuobanAppSDK from 'huoban-app-sdk'

// CommonJS
var HuobanAppSDK = require('huoban-app-sdk')

// RequireJS
define(['huoban-app-sdk'], function (HuobanAppSDK) {/*...*/})

<!-- 全局引入, 全局变量名为 `window.HuobanAppSDK` -->
<script src="//unpkg.com/huoban-app-sdk@latest/lib/HuobanAppSDK.min.js"></script>

初始化

Client: HuobanAppSDK.client()

实例化一个客户端类，用于和宿主通讯:

const client = HuobanAppSDK.client()

// 发送一个动作到宿主
client.send('hello', {word: 'i am a client'}).then(message => {
  console.log(message)
})

Host: HuobanAppSDK.host()

实例化宿主类，可以批量传入动作回调:

const host = HuobanAppSDK.host({
  init: handleClientInit
})

// 也可使用 `on` 方法增加指定动作的回调
host.on('connect', (data, respond) => {
  console.log('client connected:', data.client)
  // 在回调方法中使用 `respond` 方法回复数据
  respond('welcome')
  // 或使用第二个参数输出错误，这里代表拒绝连接
  // respond(null, 'connect refused.')
})

// 支持绑定 `*` 全局动作回调，用于接收所有动作
host.on('*', (action, data) => {
  // 注: 在全局回调中无法使用 `respond` 回复数据
  console.log('client send an action:', action, data)
})

// 给指定客户端发送动作.
// 注: 此处的 {CLIENT} 参数来自于 `connect` 动作
host.push({CLIENT}, 'app.change', {app_id: 123, name: ...})

function handleClientInit (data, respond) {
  fetchInitDataFromServer(data.app_id).then((ret) => {
    respond(ret)
  })
}

SDK API

`HuobanAppSDK.client(handlers) : Client`

初始化客户类.

handlers {Object} 包含动作和回调的对象

返回一个客户类实例 Client (继承自 Channel). 相关文档见 Channel API Docs.

示例:

HuobanAppSDK.client({
  broadcast: (data, respond) => {
    new Notification('You have a broadcast! ' + data.action)
    respond('GOT_IT')
  }
})

`HuobanAppSDK.host(handlers) : Host`

实例化宿主类.

handlers {Object} 包含动作和回调的对象

返回一个宿主类实例 Host (继承自 Channel). 相关文档见 Channel API Docs.

示例:

HuobanAppSDK.host({
  init: handleClientInit
})

`HuobanAppSDK.isClient` (属性)

Boolean 是否当前为云表格原生app环境

`HuobanAppSDK.isPC` (属性)

Boolean 是否当前为云表格web端环境

Channel API

`channel.ready(handler)`

注册一个连接(客户-宿主)成功后的回调.

handler {Function} 回调方法

尽管可以通过ready方法注册回调, 你仍然可以在连接成功之前调用 channel.send() 发送数据, 这些数据会被加入队列直到连接成功时发送.

示例:

channel.ready(() => {
  application.start()
})

`channel.send(action, data) : Promise`

通过管道发送动作到宿主/客户.

action {String} 动作
data {Any} 数据

返回一个信息实例 Message(Promise). 相关文档见 Message API Docs.

如果在连接成功前调用此方法，相关数据会被加入队列直到连接成功时发送.

示例:

// 发送特定动作, 会触发对应的回调
channel.send('notify')

// 发送包含数据的回调
channel.send('openUrl', { url: 'https://app.huoban.com/' })

`channel.push(action, data)`

通过管道推送动作到宿主/客户, 和send的区别在于无需回调.

action {String} 动作
data {Any} 数据

示例:

channel.push('broadcast', {action: 'refresh'})

`channel.on(action, handler) : {revoke, revokes, on}`

绑定指定动作的回调.

action {String} 动作名称
handler {Function} 回调方法

回调 handler 接受两个参数: data-数据, respond-回复该动作的方法.

返回一个对象, 用于解绑及继续绑定动作: {revoke, revokes, on}.

示例:

let connectBinder = channel.on('connect', (data, respond) => {
  console.log('new connection: ', data)
  respond('ok')
})
// 在必要的时候解绑
connectBinder.revoke()
// 存在多个回调时这样解绑
connectBinder.revokes.forEach(revoke => revoke())

`channel.off(action, handler)`

移除动作回调.

action {String} 指定要移除的动作, 传入*会移除所有回调
[handler] {Function} (可选) 移除指定回调, 省略此参数则移除所有action对应的回调

示例:

 // 移除指定的`handleClientInit`回调
channel.off('init', handleClientInit)

// 移除所有`init`动作回调
channel.off('init')

// 清空所有回调
channel.off('*')

`channel.emit(action, data, respond)`

触发指定动作的回调.

action {String} 动作名称
[data] {Any} (可选) 数据
[respond] {Function} (可选) 回复方法

示例:

 channel.emit('connect', {app_id: 123, ...})

Client API

Client 继承自 Channel

`client.init(applicationId) : Promise`

客户端获取初始化数据. 这应该是应用加载后发起的第一个动作

applicationId 分配的应用id

返回一个 Promise 实例, resolve 时会传入以下结构的 data:

user {Object} 当前登录用户数据
table {Object} 当前表格数据
ticket {String} 宿主发放的票据, 用于请求接口

示例:

client.init(applicationId).then((data) => {
  let {user, ticket, table} = data
})

`client.openWebPage(url, title)`

请求宿主使用新页面_(不同端对应的页面概念不同)_ 打开指定url, 并设置标题为title.

url {String} 要加载的地址
title {String} 指定的页面标题

`client.closeWebPage()`

请求宿主关闭当前页(在openWebPage打开的页面中才生效).

`client.setTitle(title)`

设置当前页面的标题.

title {String} 页面标题

`client.openItemDetail(itemId)`

请求宿主打开默认的item详情页.

itemId {Integer} 数据的id

`client.openItemList()`

请求宿主打开默认的item列表页.

`client.openItemDiff(itemId, fromRevId, toRevId, opts = {})`

请求宿主打开diff查看组件.

itemId {Integer} 对应数据的id
fromRevId {Integer} 旧版本号
toRevId {Integer} 新版本号
opts {Object} 附加参数, 用于diff展示
- field_id {Integer} 指定展示字段的id
- created_by {Object} 修改者
- created_by_id {Integer} 修改者的id
- updated_on {String} 修改时间

示例:

let itemId = 6078229
let fromRevId = 7308234
let toRevId = 7308410
client.openItemDiff(itemId, fromRevId, toRevId, {
  field_id: 3034388,
  created_by: {name: 'airwin', user_id: 11003, avatar: {}, ...},
  created_by_id: 11003,
  updated_on: '2016-07-31 11:22:33'
})

`client.openFilter(table, filters, fn)`

此方法使用fn参数接收回调, 而非返回Promise

请求宿主打开筛选器组件.

table {Object} 表格对象
filters {Object} 默认筛选条件
fn {Function} 接收筛选数据的回调: fn(data, error)
- data {Object} 成功时回调的数据, 如: {filters: {and: [{field: 110001, query: {..}}, ..]}}
  - filters {Object} 筛选条件对象
- error {Object} 错误信息如: {cancelled: true} 用户取消了本次操作, {message: 'default value error'} 特定错误
  - cancelled {Boolean} 用户取消了操作时, 此项为true
  - message {String} 错误描述

示例:

client.openFilter(table, null, (data) => {
  console.log('filters changed:', data.filters)
})

`client.openUserPicker(opts, fn)`

此方法使用fn参数接收回调, 而非返回Promise

请求宿主打开成员选择器.

opts {Object} 选择器参数
- values {Array} 默认选择的用户id数组, 如: [11001, 11003]
- multi {Boolean} 是否允许多选
- required {Boolean} 是否至少选择一个
- title {String} 自定义选择器的标题
- placement {String} (只对web端有效) 选择器相对于触发元素的位置, 可选: left-bottom/right-bottom/left-top/right-top, 默认为: 'right-bottom'
- width {Integer} (只对web端有效) 选择器的宽度
fn {Function} 回调方法: fn(data, error)
- data {Object} 回调的数据如: {users: [{user_id: 11001, name: 'test1'}, {user_id: 11003, name: 'test2'}, ...]}
  - users {Array} 选择的用户对象组成的数组
- error {Object} 错误信息如: {cancelled: true} 用户取消了本次操作, {message: 'default value error'} 对应特定的错误
  - cancelled {Boolean} 用户取消了操作时, 此项为true
  - message {String} 错误描述

示例:

client.openUserPicker({multi: true, values: [11001, 11003]}, (data) => {
  console.log('users picked:', data.users)
})

`client.openDatePicker(opts, fn)`

此方法使用fn参数接收回调, 而非返回Promise

请求宿主打开日期选择器.

opts {Object} 选择器参数
- [value] {String} (可选) 默认值
- [type] {String} 选择器类型: date/time/datetime
- [showClear] {Boolean} 是否展示清除按钮用于清空已选日期
- [showToday] {Boolean} 是否展示今天按钮用于选择当天日期
- placement {String} (只对web端有效) 选择器相对于触发元素的位置, 可选: left-bottom/right-bottom/left-top/right-top, 默认为: 'right-bottom'
fn {Function} 回调: fn(data, error)
- data {Object} 回调的数据, 如: {datetime: '2016-07-28 12:33', date: '2016-07-28', time: '12:33'}
  - [datetime] {String} (可选) 完整的日期+时间
  - [date] {String} (可选) 选择的日期
  - [time] {String} (可选) 选择的时间
- error {Object} 错误信息如: {cancelled: true} 用户取消了本次操作, {message: 'default value error'} 对应特定的错误
  - cancelled {Boolean} 用户取消了操作时, 此项为true
  - message {String} 错误描述

示例:

client.openDatePicker({value: '2016-07-27', type: 'date'}, (data) => {
  console.log('date picked:', data.date)
})

`client.openRichEditor(opts, fn)`

此方法使用fn参数接收回调, 而非返回Promise

请求宿主打开富文本编辑器.

opts {Object} 选择器参数
- title {String} 编辑器的标题
- [value] {String} (可选) 默认文本
fn {Function} 回调: fn(data, error)
- data {Object} 回调的数据, 如: {value: '
  哈哈
  '}
  - value {String} 编辑后的富文本
- error {Object} 错误信息如: {cancelled: true} 用户取消了本次操作, {message: 'default value error'} 对应特定的错误
  - cancelled {Boolean} 用户取消了操作时, 此项为true
  - message {String} 错误描述

`client.openShare(opts, fn)`

此方法使用fn参数接收回调, 而非返回Promise

请求宿主打开分享组件.

opts {Object} 分享参数
- [title] {String} 分享的标题
- [content] {String} 分享的描述
- [image] {String} 分享的图片(logo)
- [url] {String} 分享数据的链接
- [type] {String} 分享的类型, 可以为: url(默认链接形态的分享)/image(图片)
- [content_info] {Object} 分享内容的附加信息, 比如type=image时: {size: 1024}
- [via] {String} 指定分享方式, 可以为: wechat(微信聊天)/wechat_timeline(微信朋友圈)/qq(腾讯QQ)/weibo(微博)/clipboard(系统剪切板)/browser(浏览器)/tongren(同仁app)
fn {Function} 回调: fn(data, error)
- data {Object} 成功时回传的数据, 如: {via: 'wechat'}
  - [via] {String} 成功分享时使用的分享方式, 可以为: wechat(微信聊天)/wechat_timeline(微信朋友圈)/qq(腾讯QQ)/weibo(微博)/clipboard(系统剪切板)/browser(浏览器)/tongren(同仁app)
- error {Object} 错误信息如: {cancelled: true} 用户取消了本次操作, {message: 'default value error'} 对应特定的错误
  - cancelled {Boolean} 用户取消了操作时, 此项为true
  - message {String} 错误描述

示例:

client.openShare({title: 'huoban', content: 'welcome', url: 'https://app.huoban.com'}, (data, error) => {
  if (!error) {
    console.log('分享成功:', data.via)
  } else {
    console.log('分享失败')
  }
})

`client.getSpaceMembers(opts) : Promise`

从宿主请求获取全部的工作区成员.

opts {Object} 参数
- [keyword] {String} (可选) 搜索关键字

返回一个 Promise 实例, resolve时传入 data:

members {Array} 成员对象组成的数组, 如: [{name: 'test1', user_id: 11003, avatar:..}, ..]

示例:

client.getSpaceMembers({keyword: 'air'}).then((data) => {
  console.log('got members:', data.members)
})

`client.openAttachment(fileInfo)`

请求宿主展示/打开附件.

fileInfo {Object} 附件数据

`client.genQRCode(text) : Promise`

生成二维码(dataURL格式).

text {Object} 要生成的文本

返回一个 Promise 实例, resolve时传入 data:

dataURL {String} base64编码后的dataURL, 用于在image的src中使用

示例:

client.genQRCode('hello world').then((data) => {
  console.log('got dataURL:', data.dataURL)
})

`client.scanQRCode(opts) : Promise`

扫描二维码. (只在原生宿主环境生效)

opts {Object} 参数
- needResult {Boolean} 为 true 时将扫描结果返回

返回一个 Promise 实例, resolve时传入 data:

result {String} 扫描结果

示例:

client.scanQRCode().then((data) => {
  console.log('got result:', data.result)
})

`client.getLocation(opts = {}, fn)`

此方法使用fn参数接收回调, 而非返回Promise

获取当前位置.

opts {Object} 参数
- [position] {Object} (可选) 当前坐标(gcj02格式) 如: {lng: 116.397428, lat: 39.90923}
- enableHighAccuracy {Boolean} 是否高精度 (GPS), 默认为: true
- timeout {Integer} 超时时间 (单位: 毫秒), 默认为 10000
- convert {Boolean} 是否转化坐标 (wgs84 to gcj02), 默认为 true
- title {String} 展示的标题
fn {Function} 接收筛选数据的回调: fn(data, error)
- data {Object} 成功时回调的数据
  - location {Object} 当前位置信息 如: {name: 'xx', address: 'xx', distance: 10, lng: 116.32, lat: 40.033}
- error {Object} 错误信息如: {cancelled: true} 用户取消了本次操作, {message: 'default value error'} 特定错误
  - cancelled {Boolean} 用户取消了操作时, 此项为true
  - message {String} 错误描述

示例:

client.getLocation({}, (data, error) => {
  console.log('got location:', data, error)
})

`client.openUserProfile(userId, opts)`

请求宿主打开用户卡片.

userId {Integer} 用户id
opts {Object} 配置参数
- placement {String} (只在web端生效) 卡片相对于触发元素的位置, 可选: left-bottom/right-bottom/left-top/right-top/bottom/top, 默认为: 'bottom'

`client.broadcast(action, data)`

向所有其他客户端发送广播.

action {String} 广播的动作
[data] {Any} (可选) 广播的数据

`client.setPageConfig(config)`

设置当前页面的特性. (只在原生宿主环境生效)

config {Object}
- landscape {Object} 横屏时页面特性如: {nav_bar: false, bottom_bar: false}
  - nav_bar {Boolean} 横屏时是否展示导航栏
  - bottom_bar {Boolean} 横屏时是否展示底栏

`client.setNavigationBarVisibility(isVisible)`

请求宿主显示/隐藏导航栏. (只在原生宿主环境生效)

isVisible {Boolean} 是否可见

`client.setBottomToolBarVisibility(isVisible)`

请求宿主显示/隐藏底栏. (只在原生宿主环境生效)

isVisible {Boolean} 是否可见

Message API

`message.then(handler)`

注册接收消息的回调.

handler {Function} 回调

示例:

const client = HuobanAppSDK.client()
client.send('init', { app_id: 100117 }).then((data) => {
  console.log(data.ticket, data.user, data.table)
})

`respond([data])`

回复一条收到的信息.

此方法作为消息回调的第二个参数传入.

[data] {Any} (可选) 回复的数据

Author & License

created by airwin and released under the MIT license.

Files

README_CN.md

Latest commit

History

README_CN.md

File metadata and controls

伙伴云表格 应用 JS-SDK (英文版)

引入

初始化

SDK API

HuobanAppSDK.client(handlers) : Client

HuobanAppSDK.host(handlers) : Host

HuobanAppSDK.isClient (属性)

HuobanAppSDK.isPC (属性)

Channel API

channel.ready(handler)

channel.send(action, data) : Promise

channel.push(action, data)

channel.on(action, handler) : {revoke, revokes, on}

channel.off(action, handler)

channel.emit(action, data, respond)

Client API

client.init(applicationId) : Promise

client.openWebPage(url, title)

client.closeWebPage()

client.setTitle(title)

client.openItemDetail(itemId)

client.openItemList()

client.openItemDiff(itemId, fromRevId, toRevId, opts = {})

client.openFilter(table, filters, fn)

client.openUserPicker(opts, fn)

client.openDatePicker(opts, fn)

client.openRichEditor(opts, fn)

client.openShare(opts, fn)

client.getSpaceMembers(opts) : Promise

client.openAttachment(fileInfo)

client.genQRCode(text) : Promise

client.scanQRCode(opts) : Promise

client.getLocation(opts = {}, fn)

client.openUserProfile(userId, opts)

client.broadcast(action, data)

client.setPageConfig(config)

client.setNavigationBarVisibility(isVisible)

client.setBottomToolBarVisibility(isVisible)

Message API

message.then(handler)

respond([data])

Author & License

伙伴云表格应用 JS-SDK (英文版)

`HuobanAppSDK.client(handlers) : Client`

`HuobanAppSDK.host(handlers) : Host`

`HuobanAppSDK.isClient` (属性)

`HuobanAppSDK.isPC` (属性)

`channel.ready(handler)`

`channel.send(action, data) : Promise`

`channel.push(action, data)`

`channel.on(action, handler) : {revoke, revokes, on}`

`channel.off(action, handler)`

`channel.emit(action, data, respond)`

`client.init(applicationId) : Promise`

`client.openWebPage(url, title)`

`client.closeWebPage()`

`client.setTitle(title)`

`client.openItemDetail(itemId)`

`client.openItemList()`

`client.openItemDiff(itemId, fromRevId, toRevId, opts = {})`

`client.openFilter(table, filters, fn)`

`client.openUserPicker(opts, fn)`

`client.openDatePicker(opts, fn)`

`client.openRichEditor(opts, fn)`

`client.openShare(opts, fn)`

`client.getSpaceMembers(opts) : Promise`

`client.openAttachment(fileInfo)`

`client.genQRCode(text) : Promise`

`client.scanQRCode(opts) : Promise`

`client.getLocation(opts = {}, fn)`

`client.openUserProfile(userId, opts)`

`client.broadcast(action, data)`

`client.setPageConfig(config)`

`client.setNavigationBarVisibility(isVisible)`

`client.setBottomToolBarVisibility(isVisible)`

`message.then(handler)`

`respond([data])`