# @cloudbase/weda-cloud-sdk
微搭 cloud sdk, 微搭应用框架内置, 用户无需手动引入.

微搭应用集成本sdk的文档请参考 readme-inner.md

## 对外方法/属性(用户可直接访问和使用)
在低码应用中, 本 SDK 对外方法均可通过全局对象 `app.cloud` 访问, 如:

```ts
// 访问当前用户信息
const currentUser = app.cloud.currentUser

// 调用数据源
app.cloud.callDataSource({
  dataSourceName: 'user',
  methodName: 'wedaGetRecords',
  params: {}
}).then(res => console.log(res))
```

app为低码的全局对象, 以下文档说明时均省略 `app`

### cloud.version
`cloud.version`为一个字符串常量, cloud-sdk 的版本号, 调试时可用于确认应用使用的cloud-sdk版本号

### cloud.callDataSource
调用数据源方法

该方法还有两个别名 `cloud.callModel` 调用模型数据源 、 `cloud.callConnector` 调用连接器(包括自定义连接器)

方法定义
```ts
(params: ICallDataSourceParams) => Promise<IDsResponse>

// params.params 即为数据源方法中定义的入参
// IDsResponse 则为数据源方法中的出参

/**
 * 调用数据源的参数
 */
interface ICallDataSourceParams {
  /**
   * 模型数据源/连接器的标志
   */
  name: string
  /**
   * 模型数据源/连接器的标志
   * @deprecated 已废弃, 请使用 name 替代
   */
  dataSourceName: string
  /** 数据源方法名 */
  methodName: string
  /** 方法参数 */
  params: any
  /** 额外的配置选项 */
  options?: {
    /** 请求过程中是否显示 loading */
    showLoading?: boolean
    /** 请求结束了, 是否显示toast */
    showToast?: boolean
  }
}
```

示例:
```ts
// 调用 user 数据源内置的 wedaCreate 方法, 新建一条记录
cloud.callDataSource({
  dataSourceName: 'user',
  methodName: 'wedaCreate',
  params: {
    name: 'Joe',
    age: 67
  }
}).then(res => console.log(res._id))
```

### cloud.getTempFileURL
获取云存储文件的临时访问链接, 即将 `cloud://xxxx` 协议的私有地址转换为 `http` 协议的正常地址

**注意: `cloud://xxx` 协议地址错误 或者无访问权限等, 该方法将不会返回地址 **

方法定义:
```ts
// 获取单个cos文件的公有访问地址, 获取成功则返回 字符串即链接地址, 失败则为 undefined
cloud.getTempFileURL(fileId: string) => Promise<string | undefined>
// 获取多个时, 返回结果为对象, 只包含获取成功的fileId结果, key 为 fileId, value 为其对应的链接地址
cloud.getTempFileURL(fileIds: string[]) => Promise<Record<string, string>>
```

示例:
```ts
cloud.getTempFileURL('cloud://tcb-demo-10cf5b.7463-tcb-demo-10cf5b-1302484483/images/pic_netbian_com/001714-162653863412dd.jpg')
  .then(url => console.log(url))

cloud.getTempFileURL([
  'cloud://tcb-demo-10cf5b.7463-tcb-demo-10cf5b-1302484483/images/pic_netbian_com/001714-162653863412dd.jpg',
  'cloud://tcb-demo-10cf5b.7463-tcb-demo-10cf5b-1302484483/images/pic_netbian_com/001935-16159115757f04.jpg'
]).then(res => {
  console.log(res['cloud://tcb-demo-10cf5b.7463-tcb-demo-10cf5b-1302484483/images/pic_netbian_com/001935-16159115757f04.jpg'])
})
```


### cloud.dataSources
数据源对象, 亦可用于调用数据源方法, 功能与 `cloud.callDataSource`.

方法定义:
```ts
cloud.dataSources.<dataSourceName>.<methodName>(params: IDsParams) => Promise<IDsResponse>

/**
 * dataSourceName 为数据源标识
 * methodName 即数据源方法的标识
 * IDsParams 即数据源方法的入参
 * IDsResponse 即方法的出参
 */
```

示例:
```ts
cloud.dataSources.user.wedaCreate({name: 'Joe', age: 67}).then(res => console.log(res._id))
```

**注意**
若调用的数据源或数据源方法不存在, 会报语法错误


### cloud.setDataSourceDefaultParams
为数据源的下的所有方法设置默认参数, 设置后会影响 `cloud.callDataSource` 和 `cloud.dataSources` 两种数据源调用方式

方法定义:
```ts
/**
 * dataSourceName 数据源标识
 * params 默认参数, 应该为对象
 */
(dataSourceName: string, params: Record<string, any>) => void
```

示例:
```ts
cloud.setDataSourceDefaultParams('user', {age: 10})

//  此时会将 Jim 的 age 设置为 10
cloud.dataSources.user.wedaCreate({name: 'Jim'}).then(res => console.log(res._id))
```

**注意**
本方法会影响数据源下所有方法的入参, 应当仅在数据源下的方法有某些公共参数时才使用本方法


### cloud.utils
cloud-sdk的辅助工具方法

#### cloud.utils.wrapperDatasourceMethod
传入数据源的名称和方法名称, 返回该数据源方法的函数

方法定义:
```ts
(options: IWrapperDatasourceOptions) => ((params: IDsParams) => Promise<IDsResponse>)

interface IWrapperDatasourceOptions {
  /** 数据源名称 */
  dataSourceName: string;
  /** 底层查询使用的数据源方法 */
  methodName: string;
}

/**
 * IDsParams 数据源方法的入参
 * IDsResponse 数据源方法的出参
 */
```

示例:
```ts
const createUser = cloud.utils.wrapperDatasourceMethod({dataSourceName: 'user', methodName: 'wedaCreate'});
// createUser 与 cloud.dataSources.user.wedaCreate 功能是一样

createUser({name: 'Ashram', age: '38'}).then(res => console.log(res._id))
```

**注意**
`cloud.utils.wrapperDatasourceMethod` 与 `cloud.dataSources.<dataSourceName>.<methodName>` 区别:
* `cloud.utils.wrapperDatasourceMethod` 为函数调用
* 若数据源标识或方法名不存在, 调用`cloud.utils.wrapperDatasourceMethod` 时不会报错, 返回的函数在使用时才会报错

### cloud.getCloudInstance
返回云开发web-sdk初始化后的实例(无需关心tcb环境信息及认证登录的处理), 即  `tcb.init` 后返回的对象, 可用该对象直接调用tcb的各种能力.  

方法定义:  
`() => Promise<CloudInstance>`


示例:
```ts
cloud.getCloudInstance().then(app => {
  // 调用云函数
  app.callFunction({
    name: "test",
    data: { a: 1 }
  })
  .then((res) => {
    const result = res.result; //云函数执行结果
  })
})
```
云开发web-sdk的详细用法可参考官方文档: <https://docs.cloudbase.net/api-reference/webv2/initialization.html>

### cloud.callFunction
调用云开发的云函数, 与 `cloud.getCloudInstance` 示例中的效果大体一致.

方法定义:
```ts
(params: ICallFunctionParams, parseOptions?: IParseOptions) => Promise<any>

/**
 * 调用云函数的参数
 */
interface ICallFunctionParams {
  /** TCB云函数名称 */
  name: string
  /** 云函数接收的参数 */
  data?: any
}

/** 解析云开发云函数调用结果配置 */
interface IParseOptions {
  /**
   * 解析 云开发云函数的通用response 包装
   *    为true, 则返回 res.result, 此时会丢失 res.requestId 信息
   */
  unwrapResult?: boolean
  /**
   * 解析业务信息
   *  需配合 unwrapResult 使用
   *  为 true 时, res.result.code 非 0 抛出错误, 为 0 则返回 res.result.data
   */
  parseBusinessInfo?: boolean
}
```

示例:
```ts
cloud.callFunction({
 name: "test",
 data: { a: 1 }
})
.then((res) => {
 const result = res; //云函数执行结果
})
```

### cloud.callCommonService
调用微搭后台公共服务(内部使用)

方法定义:
```ts
(params: ICallCommonService) => Promise<any>

/**
 * 调用云函数的参数
 */
interface ICallCommonService {
  /** 方法名 */
  methodName: string
  /** 方法参数 */
  params: any
}

```

### cloud.callWedaApi
调用微搭后端API服务

方法定义:
```ts
(params: ICallWedaApiParams) => Promise<any>

interface ICallWedaApiParams {
  /** 方法名称 */
  action: string
  /**
   * 方法的自定义参数
   *  其中 envType, envId, uid, source 均无需填写
   */
  data?: Record<string, any>
  /**
   * 是否自动将 data 的key 改为大写驼峰
   *  默认为 true, 即使用时 data 可以采用小驼峰的 key
   */
  capitalizeDataKey?: boolean
}
```

示例:
```ts
// 查询当前用户的weda Id
cloud.callWedaApi({
  action: 'DescribeWedaUserId'
}).then(res => console.log(res))
```

### cloud.callWorkflow
调用微搭流程服务

方法定义:
```ts
(params: ICallWedaApiParams) => Promise<any>

interface ICallWedaApiParams {
  /** 方法名称 */
  action: string
  /**
   * 方法的自定义参数
   *  其中 envType, envId, uid, source 均无需填写
   */
  data?: Record<string, any>
  /**
   * 是否自动将 data 的key 改为大写驼峰
   *  默认为 true, 即使用时 data 可以采用小驼峰的 key
   */
  capitalizeDataKey?: boolean
}
```

示例:
```ts
cloud.callWorkflow({
  action: 'DescribeProcessInstanceDetails',
  data: {
    processInstanceId: 'xxxxxx'
  }
}).then(res => console.log(res))
```

### cloud.getDataSourceViewId
查询数据源的 viewId 信息, 当找不到数据源时则返回`undefined`. 

方法定义:
```ts
(params: IDsViewIdFilterOptions) => string | undefined

/**
 *  string: 数据源标识, 即 name
 *  function: 自定义数据源查找条件
 *  {key, val}: 查找数据源信息中字段为 key, 值为 val 的项
 */
type IDsViewIdFilterOptions = string | ((ds: any) => boolean) | ({val: string, key: string});
```

示例:
```ts
const viewId = cloud.getDataSourceViewId('user');
```

返回 `undefined` 有以下几种场景:
* 找不到对应的数据源, 可能该数据源已被删除, 或者应用在编辑时未通过合适的方式声明使用了该数据源导致生成应用时未包函该数据源的信息
* 查找的数据源非自建数据源, 即 `type` 非 `database`

### cloud.getDataSourceProfile
查询数据源的详情信息, 找不到则返回 `undefined`

方法定义:
```ts
(params: IDsFilterOptions) => IDsProfile | undefined

/**
 *  string: 数据源标识, 即 name
 *  function: 自定义数据源查找条件
 *  {key, val}: 查找数据源信息中字段为 key, 值为 val 的项
 */
type IDsFilterOptions = string | ((ds: any) => boolean) | ({val: string, key: string});

/**
 * IDsProfile为 数据源的摘要信息, 并非完整信息, 包含了完整数据源信息的下属字段
 *  {id, title, type, name, schema, childDataSourceNames, methods }
 * 其中 methods 数组成员只包含方法的 { type, name }
 */
```

### cloud.checkAuth
查询用户对资源对访问权限

方法定义:
```ts
(params: ICheckAuthParams) => Promise<Array<ResourceCheckInfo>>

/**
 * 权限信息
 *  https://tcloud-dev.oa.com/document/product/1505/57799?!preview&!document=1
 */
interface ICheckAuthParams {
  /**
   * 资源类型 （1：应用，2：数据源，3：流程）
   */
  type: '1' | '2' | '3',
  /**
   * 子资源类型 （1：应用，2：页面，3：按钮）
   */
  subType: '1' | '2' | '3'
  /**
   * 父资源ID （对于应用：只有Type =1/subType =3 此值才有意义）
   */
  parentResourceId?: string
};
// ResourceCheckInfo 结构可参考 https://tcloud-dev.oa.com/document/product/1505/53371?!preview&preview_docmenu=1&lang=cn&!document=1#ResourceCheckInfo
```