# CloudCC 前端 SDK（cloudcc-ccdk）使用指南

> 本文档参考 CloudCC 官方「前端 SDK
> 参考」整理而成：[前端SDK参考](https://help.cloudcc.cn/product03/sdkcan-kao/)。\
> 目标：指导在自定义组件、客户端脚本等前端场景中正确安装和使用
> `$CCDK`，并按模块梳理常用 API。

---

## 1. 安装与全局引入

### 1.1 PC 端（Web）

全局可通过 `window.$CCDK` 访问各模块：

```js
window.$CCDK.CCMessage.showMessage("Hello CloudCC");
```

### 1.2 App 小程序端（DCloud）

- 通过 DCloud 插件市场安装 `h5-ccdk`
- 具体用法参考官方 `h5-ccdk` 文档（此处仅关注 Web 端 `cloudcc-ccdk`）

---

## 2. 模块概览

常用模块按功能大致分为：

- **加载与网络**：`CCLoad`、`CCHttp`
- **后端类调用**：`CCCommon`
- **认证与用户**：`CCToken`、`CCUser`
- **对象数据与页面导航**：`CCDetail`、`CCList`、`CCPage`
- **事件与工具**：`CCBus`、`CCCrypto`、`CCUtils`
- **日志与消息**：`CCLog`、`CCMessage`
- **OpenAPI 封装**：`CCOpenAPI`
- 其他：`CCSide`、`CCApplication`、`CCCall`、`CCRenderer`、`CCLoading`、`CCI18n`
  等

以下按高频使用场景做简要说明与示例。

---

## 3. CCLoad：加载远程 JS 资源

### 3.1 `loadJs(src): Promise`

在 PC 端通过 JS 动态加载远程脚本：

```js
const p = $CCDK.CCLoad.loadJs(
  "https://cdn.bootcdn.net/ajax/libs/echarts/6.0.0/echarts.common.js",
);

p.then(() => {
  // 脚本加载完成
}).catch(console.error);
```

- 仅 PC 有效（H5/小程序/APP 不支持）

**参数说明：**

| 参数  | 说明         | 类型     | 可选值 | 默认值 |
| ----- | ------------ | -------- | ------ | ------ |
| `src` | 远程 JS 地址 | `string` | —      | 必填   |

### 3.2 `createLoadJsComponent()`

创建自定义标签用来加载 JS：

```js
$CCDK.CCLoad.createLoadJsComponent();
// 在模板中：
// <cc-load-script src="js上线地址"></cc-load-script>
```

`<cc-load-script>` 组件属性：

| 属性  | 说明         | 类型     | 可选值 | 默认值 |
| ----- | ------------ | -------- | ------ | ------ |
| `src` | 远程 JS 地址 | `string` | —      | 必填   |

---

## 4. CCHttp：简单网络请求

> 基于 axios 封装，默认已带上必要头信息，适合在 CloudCC
> 场景下调用外部/内部接口。

常用方法：`get` / `post` / `put` / `patch` / `postParams`，统一返回 Promise。

```js
const data = { name: "zhangsan" };

$CCDK.CCHttp.post("/api/demo", data)
  .then((res) => {
    console.log("res", res);
  })
  .catch((error) => {
    console.log("error", error);
  });
```

以 `get(url, data, responseType, config)` 为例，参数说明如下：

| 参数           | 说明         | 类型     | 可选值 | 默认值 |
| -------------- | ------------ | -------- | ------ | ------ |
| `url`          | 接口请求地址 | `string` | —      | `''`   |
| `data`         | 查询参数     | `object` | —      | `{}`   |
| `responseType` | 响应类型     | `string` | —      | `''`   |
| `config`       | axios 配置   | `object` | —      | `{}`   |

其他方法参数形态类似：

- `post(url, data, responseType, config)`
- `put(url, data)` / `patch(url, data)` / `postParams(url, data)`

---

## 5. CCCommon：访问 CloudCC 自定义类（接口）

### `post(className, methodName, params, config): Promise`

用于在前端调用 CloudCC 后端自定义类，避免自己拼接 URL：

```js
const className = "test";
const methodName = "func1";
const params = [
  { argType: "java.lang.String", argValue: "hello" },
  { argType: "java.lang.String", argValue: "world" },
];
const config = { timeout: 60000 };

$CCDK.CCCommon.post(className, methodName, params, config)
  .then((res) => {
    const data = res.data;
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });
```

- 仅 PC 有效

**参数说明：**

| 参数                 | 说明                     | 类型     | 可选值 | 默认值 |
| -------------------- | ------------------------ | -------- | ------ | ------ |
| `className`          | 自定义类名               | `string` | —      | `''`   |
| `methodName`         | 自定义类中的方法名       | `string` | —      | `''`   |
| `params`             | 方法入参列表             | `Array`  | —      | `[]`   |
| `params[*].argType`  | Java 参数类型            | `string` | —      | —      |
| `params[*].argValue` | 参数值                   | `any`    | —      | —      |
| `config`             | 请求配置（如 `timeout`） | `object` | —      | `{}`   |

---

## 6. CCToken：令牌管理

### 6.1 `getToken(): string`

```js
const token = $CCDK.CCToken.getToken();
```

**返回值：**

| 返回值  | 说明             | 类型     |
| ------- | ---------------- | -------- |
| `token` | 当前用户登录令牌 | `string` |

### 6.2 `setToken(token): void`

```js
$CCDK.CCToken.setToken("your-token");
```

| 参数    | 说明     | 类型     | 可选值 | 默认值 |
| ------- | -------- | -------- | ------ | ------ |
| `token` | 新的令牌 | `string` | —      | 必填   |

### 6.3 `clearToken(): void`

```js
$CCDK.CCToken.clearToken();
```

PC/H5/小程序均可用（APP 暂不支持）。

---

## 7. CCUser：当前登录用户信息

### 7.1 `getUserInfo(keyName): object`

```js
const userInfo = $CCDK.CCUser.getUserInfo(); // 默认 key 为 cc_user_info
```

| 参数      | 说明                     | 类型     | 可选值 | 默认值           |
| --------- | ------------------------ | -------- | ------ | ---------------- |
| `keyName` | 存储用户信息的键名，可选 | `string` | —      | `"cc_user_info"` |

**返回值：**

| 返回值     | 说明             | 类型     |
| ---------- | ---------------- | -------- |
| `userInfo` | 当前登录用户信息 | `object` |

### 7.2 `setUserInfo(userInfo, domain, keyName): void`

```js
$CCDK.CCUser.setUserInfo({ name: "zhangsan" });
```

| 参数       | 说明             | 类型     | 可选值 | 默认值           |
| ---------- | ---------------- | -------- | ------ | ---------------- |
| `userInfo` | 用户详细信息对象 | `object` | —      | `{}`             |
| `domain`   | 域名             | `string` | —      | 当前所在域名     |
| `keyName`  | 存储键名         | `string` | —      | `"cc_user_info"` |

---

## 8. CCDetail：对象详情

> 操作标准详情页数据，常配合客户端脚本/自定义组件使用。

### 8.1 `getDetail(apiname?, detailId?): object`

```js
// 获取当前详情页全部数据
const detail = $CCDK.CCDetail.getDetail();

// 获取当前详情页某字段的值
const field = $CCDK.CCDetail.getDetail("name");
const value = field.value;
```

| 参数       | 说明                                          | 类型     | 可选值 | 默认值  |
| ---------- | --------------------------------------------- | -------- | ------ | ------- |
| `apiname`  | 指定字段 API 名称，不传则返回整条详情         | `string` | —      | `null`  |
| `detailId` | 指定详情记录 ID，不传则使用最近访问的详情记录 | `string` | —      | 最新 ID |

**返回值：**

- 不传 `apiname`：返回对象详情整体结构
- 传入 `apiname`：返回该字段的包装对象（常见属性如 `value`、`label` 等）

### 8.2 `setDetail(detail): void`

```js
$CCDK.CCDetail.setDetail({
  id: "00120231...",
  detail: [/* 详情数据 */],
});
```

| 参数            | 说明         | 类型     | 可选值 | 默认值 |
| --------------- | ------------ | -------- | ------ | ------ |
| `detail`        | 详情数据对象 | `object` | —      | 必填   |
| `detail.id`     | 详情记录 ID  | `string` | —      | 必填   |
| `detail.detail` | 详情字段数组 | `Array`  | —      | 必填   |

### 8.3 其他常用方法

- `getDetailId()` / `setDetailId(id)`：获取/设置当前详情页 ID
- `refreshRelatedList(ids)`：刷新相关列表
- `getRelatedSelected(recordId, detailId)`：获取相关列表选中记录

---

## 9. CCList：对象列表页（视图页）

### 9.1 `getSelected(): { ids: string[] }`

```js
const { ids } = $CCDK.CCList.getSelected();
```

**返回值：**

| 字段  | 说明                     | 类型       |
| ----- | ------------------------ | ---------- |
| `ids` | 当前列表页中选中 ID 集合 | `string[]` |

### 9.2 `getViewId()`、`getViewInfo()`

```js
const viewId = $CCDK.CCList.getViewId();
const viewInfo = $CCDK.CCList.getViewInfo();
// 包含 ids、viewId、prefix、objid、objectApi 等
```

`getViewId()`：

| 返回值   | 说明        | 类型     |
| -------- | ----------- | -------- |
| `viewId` | 当前视图 ID | `string` |

`getViewInfo()` 常见字段：

| 字段        | 说明             | 类型     |
| ----------- | ---------------- | -------- |
| `ids`       | 当前选中 ID 集合 | `Array`  |
| `viewId`    | 当前视图 ID      | `string` |
| `prefix`    | 对象前缀         | `string` |
| `objid`     | 对象 ID          | `string` |
| `objectApi` | 对象 API 名称    | `string` |

---

## 10. CCPage：打开/关闭 CloudCC 页面

> 在组件/脚本中以「官方方式」打开列表、详情、新建、编辑、自定义页面。

### 10.1 打开列表页 `openListPage(obj): string`

```js
const pageId = $CCDK.CCPage.openListPage({
  menuId: "aaa-223",
  prefix: "001",
  viewId: "ace1111",
  layoutType: "list", // list / Kanban / splitscreen
});
```

| 参数         | 说明     | 类型     | 可选值                                  | 默认值   |
| ------------ | -------- | -------- | --------------------------------------- | -------- |
| `menuId`     | 菜单 ID  | `string` | —                                       | 必填     |
| `prefix`     | 对象前缀 | `string` | —                                       | 必填     |
| `viewId`     | 视图 ID  | `string` | —                                       | 必填     |
| `layoutType` | 布局类型 | `string` | `"list"` / `"Kanban"` / `"splitscreen"` | `"list"` |

**返回值：**

| 返回值   | 说明             | 类型     |
| -------- | ---------------- | -------- |
| `pageId` | 打开页面唯一标识 | `string` |

### 10.2 打开详情页 `openDetailPage(obj, id, options): string`

```js
const pageId = $CCDK.CCPage.openDetailPage(
  {
    oprateType: "DETAIL",
    objectName: "客户",
    objId: "account",
    objectApi: "Account",
    prefix: "001",
  },
  "00120227805836AlIEL4",
  {
    openPlace: "menu2",
    openMode: "_self",
  },
);
```

`obj` 参数：

| 字段         | 说明               | 类型     | 可选值 | 默认值                |
| ------------ | ------------------ | -------- | ------ | --------------------- |
| `oprateType` | 页面类型           | `string` | —      | 必填（如 `"DETAIL"`） |
| `objectName` | 对象名称（展示用） | `string` | —      | 必填                  |
| `objId`      | 对象 ID            | `string` | —      | 必填                  |
| `objectApi`  | 对象 API 名称      | `string` | —      | 必填                  |
| `prefix`     | 对象前缀           | `string` | —      | 必填                  |

`id` 参数：

| 参数 | 说明    | 类型     | 可选值 | 默认值 |
| ---- | ------- | -------- | ------ | ------ |
| `id` | 记录 ID | `string` | —      | 必填   |

`options` 常用字段（节选）：

| 字段        | 说明     | 类型     | 可选值                          | 默认值    |
| ----------- | -------- | -------- | ------------------------------- | --------- |
| `pageId`    | 页面 ID  | `string` | —                               | 不传      |
| `openPlace` | 打开位置 | `string` | `"tab"` / `"menu1"` / `"menu2"` | `"menu1"` |
| `openMode`  | 打开方式 | `string` | `"_self"` / `"_blank"`          | `"_self"` |

### 10.3 打开新建/编辑页

- `openCreatePage(obj, options)`
- `openEditPage(obj, id, options)`

可通过 `defalutData` 预填字段值，适用于从组件/脚本跳转并带默认值的场景。

### 10.4 打开自定义页面 `openCustomPage(obj, options)`

```js
const pageId = $CCDK.CCPage.openCustomPage(
  { pageApi: "sayhello", data: {} },
  {
    openPlace: "dialog",
    openMode: "_blank",
    title: "菜单标题",
    height: "70vh",
    width: "70vw",
  },
);
```

`obj` 参数：

| 字段      | 说明                 | 类型     | 可选值 | 默认值 |
| --------- | -------------------- | -------- | ------ | ------ |
| `pageApi` | 自定义页面标识       | `string` | —      | 必填   |
| `data`    | 初始化数据（表单等） | `object` | —      | `{}`   |

`options` 常用字段（节选）：

| 字段          | 说明                                      | 类型      | 可选值                                                         | 默认值            |
| ------------- | ----------------------------------------- | --------- | -------------------------------------------------------------- | ----------------- |
| `pageId`      | 页面 ID，相同 ID 时复用页面               | `string`  | —                                                              | 不传              |
| `openPlace`   | 打开位置                                  | `string`  | `"dialog"` / `"tab"` / `"floatDialog"` / `"menu1"` / `"menu2"` | `"tab"`           |
| `openMode`    | 打开方式                                  | `string`  | `"_self"` / `"_blank"`                                         | `"_blank"`        |
| `title`       | 弹窗标题或菜单名称                        | `string`  | —                                                              | `''`              |
| `isIframe`    | 是否以 iframe 渲染（用于缓存自定义页面）  | `boolean` | `true` / `false`                                               | `false`           |
| `isShowClose` | 是否显示菜单关闭按钮                      | `boolean` | `true` / `false`                                               | `true`            |
| `tabAction`   | 一级/二级菜单下拉操作项配置               | `Array`   | —                                                              | `[]`              |
| `width`       | 宽度，支持 `px` / `%` / `vw`              | `string`  | —                                                              | 自动              |
| `height`      | 高度，支持 `px` / `vh`                    | `string`  | —                                                              | 自动              |
| `left`        | 距离屏幕左侧距离                          | `string`  | —                                                              | 自动              |
| `top`         | 距离屏幕顶部距离                          | `string`  | —                                                              | 自动              |
| `right`       | 距离屏幕右侧距离                          | `string`  | —                                                              | 自动              |
| `bottom`      | 距离屏幕底部距离                          | `string`  | —                                                              | 自动              |
| `isShowMenu`  | 是否显示菜单（menu1/menu2 下默认 `true`） | `boolean` | `true` / `false`                                               | 视 openPlace 而定 |

**返回值：**

| 返回值   | 说明                     | 类型     |
| -------- | ------------------------ | -------- |
| `pageId` | 打开的自定义页面唯一标识 | `string` |

### 10.5 其他

- `reOpenPage(pageId, options)`：通过 pageId 重新打开/刷新页面
- `searchPage(pageId)`：查询是否存在指定页面
- `getCurrentPage()`：获取当前页面菜单数据
- `close(pageId?)`、`refresh()`：关闭/刷新页面

---

## 11. CCBus：前端事件总线

### 11.1 `$emit(event, ...args)`

```js
$CCDK.CCBus.$emit("myevent", { foo: 1 });
```

| 参数      | 说明                 | 类型     | 可选值 | 默认值 |
| --------- | -------------------- | -------- | ------ | ------ |
| `event`   | 事件名称（唯一标识） | `string` | —      | 必填   |
| `...args` | 事件参数             | `any`    | —      | —      |

### 11.2 `$on(event, callback)`

```js
$CCDK.CCBus.$on("myevent", (payload) => {
  console.log("收到事件", payload);
});
```

| 参数       | 说明     | 类型       | 可选值 | 默认值 |
| ---------- | -------- | ---------- | ------ | ------ |
| `event`    | 事件名称 | `string`   | —      | 必填   |
| `callback` | 回调函数 | `function` | —      | 必填   |

### 11.3 `$off(event)`

```js
$CCDK.CCBus.$off("myevent");
```

| 参数    | 说明     | 类型     | 可选值 | 默认值 |
| ------- | -------- | -------- | ------ | ------ |
| `event` | 事件名称 | `string` | —      | 必填   |

---

## 12. CCMessage：前端消息提示

### 12.1 `showMessage(text, type, duration, showClose, center)`

```js
$CCDK.CCMessage.showMessage("操作成功", "success", 2000);
```

| 参数        | 说明                                 | 类型      | 可选值                                           | 默认值   |
| ----------- | ------------------------------------ | --------- | ------------------------------------------------ | -------- |
| `text`      | 提示文案                             | `string`  | —                                                | 必填     |
| `type`      | 消息类型                             | `string`  | `"success"` / `"warning"` / `"info"` / `"error"` | `"info"` |
| `duration`  | 显示时间（毫秒），`0` 表示不自动关闭 | `number`  | —                                                | `3000`   |
| `showClose` | 是否显示关闭按钮                     | `boolean` | —                                                | `false`  |
| `center`    | 文本是否居中                         | `boolean` | —                                                | `false`  |

### 12.2 `showConfirm(text, title, options, confirm, reject)`

```js
$CCDK.CCMessage.showConfirm(
  "确定要执行此操作吗？",
  "确认提示",
  { type: "warning" },
  () => {/* 确认回调 */},
  () => {/* 取消回调 */},
);
```

| 参数      | 说明                  | 类型                | 可选值 | 默认值   |
| --------- | --------------------- | ------------------- | ------ | -------- |
| `text`    | 消息正文              | `string` \| `VNode` | —      | 必填     |
| `title`   | 标题                  | `string`            | —      | `"提示"` |
| `options` | 其他配置（见下表）    | `object`            | —      | `{}`     |
| `confirm` | 点击确定时的回调      | `function`          | —      | 必填     |
| `reject`  | 点击取消/关闭时的回调 | `function`          | —      | 可选     |

`options` 常见字段：

| 字段                | 说明                   | 类型      | 可选值                                           | 默认值                     |
| ------------------- | ---------------------- | --------- | ------------------------------------------------ | -------------------------- |
| `type`              | 消息类型               | `string`  | `"success"` / `"info"` / `"warning"` / `"error"` | —                          |
| `showClose`         | 是否显示右上角关闭按钮 | `boolean` | —                                                | `true`                     |
| `showCancelButton`  | 是否显示取消按钮       | `boolean` | —                                                | `true`（confirm/prompt）   |
| `showConfirmButton` | 是否显示确定按钮       | `boolean` | —                                                | `true`                     |
| `cancelButtonText`  | 取消按钮文本           | `string`  | —                                                | `"取消"`                   |
| `confirmButtonText` | 确定按钮文本           | `string`  | —                                                | `"确定"`                   |
| `closeOnClickModal` | 点击遮罩是否关闭       | `boolean` | —                                                | `true`（alert 为 `false`） |
| `center`            | 是否居中布局           | `boolean` | —                                                | `false`                    |
| `roundButton`       | 是否圆角按钮           | `boolean` | —                                                | `false`                    |

### 12.3 `showNotification(options)`

```js
$CCDK.CCMessage.showNotification({
  title: "提示",
  message: "这是一条不会自动关闭的消息",
  duration: 0,
});
```

`options` 常见字段：

| 字段                       | 说明                                 | 类型                | 可选值                                                            | 默认值        |
| -------------------------- | ------------------------------------ | ------------------- | ----------------------------------------------------------------- | ------------- |
| `title`                    | 标题                                 | `string`            | —                                                                 | `''`          |
| `message`                  | 内容                                 | `string` \| `VNode` | —                                                                 | `''`          |
| `dangerouslyUseHTMLString` | 是否将 message 作为 HTML 处理        | `boolean`           | —                                                                 | `false`       |
| `type`                     | 类型                                 | `string`            | `"success"` / `"warning"` / `"info"` / `"error"`                  | —             |
| `duration`                 | 显示时间（毫秒），`0` 表示不自动关闭 | `number`            | —                                                                 | `4500`        |
| `position`                 | 弹出位置                             | `string`            | `"top-right"` / `"top-left"` / `"bottom-right"` / `"bottom-left"` | `"top-right"` |
| `showClose`                | 是否显示关闭按钮                     | `boolean`           | —                                                                 | `true`        |
| `onClose`                  | 关闭时回调                           | `function`          | —                                                                 | —             |
| `onClick`                  | 点击通知时回调                       | `function`          | —                                                                 | —             |

---

## 13. CCLog：日志上报

### 13.1 `reportInfoLog(logInfo)`

```js
const logInfo = {
  infoType: "debug",
  serviceName: "my app",
  infoMessage: "描述信息",
};

window.$CCDK.CCLog.reportInfoLog(logInfo);
```

`logInfo` 字段：

| 字段          | 说明     | 类型     | 可选值               | 默认值   |
| ------------- | -------- | -------- | -------------------- | -------- |
| `infoType`    | 日志类型 | `string` | `"info"` / `"debug"` | `"info"` |
| `serviceName` | 服务名称 | `string` | —                    | 项目名称 |
| `infoMessage` | 描述信息 | `string` | —                    | `""`     |
| `remark`      | 备注     | `string` | —                    | `""`     |

### 13.2 `reportErrorLog(logInfo)`

```js
const logInfo = {
  serviceName: "my app",
  errorMessage: "错误描述信息",
  printStackTraceInfo: "堆栈信息",
};

window.$CCDK.CCLog.reportErrorLog(logInfo);
```

`logInfo` 字段：

| 字段                  | 说明     | 类型     | 可选值 | 默认值   |
| --------------------- | -------- | -------- | ------ | -------- |
| `serviceName`         | 服务名称 | `string` | —      | 项目名称 |
| `errorMessage`        | 错误描述 | `string` | —      | `""`     |
| `printStackTraceInfo` | 堆栈信息 | `string` | —      | `""`     |
| `requestUrl`          | 请求地址 | `string` | —      | `""`     |
| `remark`              | 备注     | `string` | —      | `""`     |

---

## 14. CCOpenAPI：OpenAPI 封装（概览）

> 通过 CCDK 在前端直接调用 CloudCC OpenAPI，支持普通查询、分页查询、自定义 SQL
> 等。

典型方法：

- `cquery` / `cqueryWithRoleRight`
- `pageQuery` / `pageQueryWithRoleRight`
- `getQueryPermisson`
- `cqlQueryWithLogInfo` / `cqlQueryWithStatic`

示例（普通查询）：

```js
const res = await window.$CCDK.CCOpenAPI.cquery(
  clientId,
  secretKey,
  "Contact",
  "name='13213'",
  "name,createdate,createbyid",
  "false",
  {},
);

if (res.result) {
  console.log(res.data);
}
```

### 14.1 `cquery(clientId, secretKey, objectApiName, expressions, fields, isAddDelete, options)`

| 参数            | 说明                                       | 类型     | 可选值 | 默认值    |
| --------------- | ------------------------------------------ | -------- | ------ | --------- |
| `clientId`      | 客户端 ID                                  | `string` | —      | 必填      |
| `secretKey`     | 客户端密钥                                 | `string` | —      | 必填      |
| `objectApiName` | 对象 API 名称，如 `Contact`、`Account`     | `string` | —      | 必填      |
| `expressions`   | 查询条件，如 `name='13213'`                | `string` | —      | `''`      |
| `fields`        | 返回字段列表，逗号分隔                     | `string` | —      | `''`      |
| `isAddDelete`   | 是否包含已删除数据（`"true"` / `"false"`） | `string` | —      | `"false"` |
| `options`       | 额外配置（如 `baseUrl`、`timeout`）        | `object` | —      | `{}`      |

**返回值（通用结构）：**

| 字段         | 说明                      | 类型      |
| ------------ | ------------------------- | --------- |
| `result`     | 是否成功                  | `boolean` |
| `returnInfo` | 返回信息/错误说明         | `string`  |
| `returnCode` | 返回编码（如 `"1"` 成功） | `string`  |
| `data`       | 业务数据（数组或对象）    | `any`     |

### 14.2 `cqueryWithRoleRight(clientId, secretKey, objectApiName, expressions, isAddDelete, options)`

与 `cquery` 相同，但会按照当前用户权限过滤：

| 参数            | 说明               | 类型     | 默认值    |
| --------------- | ------------------ | -------- | --------- |
| `clientId`      | 客户端 ID          | `string` | 必填      |
| `secretKey`     | 客户端密钥         | `string` | 必填      |
| `objectApiName` | 对象 API 名称      | `string` | 必填      |
| `expressions`   | 查询条件           | `string` | `''`      |
| `isAddDelete`   | 是否包含已删除数据 | `string` | `"false"` |
| `options`       | 额外配置           | `object` | `{}`      |

### 14.3 `pageQuery(clientId, secretKey, objectApiName, expressions, fields, pageNUM, pageSize, options)`

| 参数            | 说明                  | 类型     | 默认值 |
| --------------- | --------------------- | -------- | ------ |
| `clientId`      | 客户端 ID             | `string` | 必填   |
| `secretKey`     | 客户端密钥            | `string` | 必填   |
| `objectApiName` | 对象 API 名称         | `string` | 必填   |
| `expressions`   | 查询条件              | `string` | `''`   |
| `fields`        | 返回字段列表          | `string` | `''`   |
| `pageNUM`       | 当前页码（从 1 开始） | `number` | 必填   |
| `pageSize`      | 每页条数              | `number` | 必填   |
| `options`       | 额外配置              | `object` | `{}`   |

附加返回字段（分页）：

| 字段         | 说明         | 类型      |
| ------------ | ------------ | --------- |
| `pageNUM`    | 当前页码     | `number`  |
| `pageSize`   | 每页条数     | `number`  |
| `totalCount` | 总记录数     | `number`  |
| `pageCount`  | 总页数       | `number`  |
| `hasPre`     | 是否有上一页 | `boolean` |
| `hasNext`    | 是否有下一页 | `boolean` |

### 14.4 其他 OpenAPI 方法（简要参数说明）

- `pageQueryWithRoleRight(clientId, secretKey, objectApiName, expressions, pageNUM, pageSize, options)`
  - 同 `pageQuery`，但增加权限过滤；`options` 可包含 `fields`。
- `getQueryPermisson(clientId, secretKey, objectApiName, options)`
  - `objectApiName` 可传多个对象（逗号分隔），返回每个对象的查询权限与
    `shareSql`。
- `cqlQueryWithLogInfo(clientId, secretKey, objectApiName, expressions, options)`
  - `expressions` 为 CQL / SQL 语句，受权限配置控制。
- `cqlQueryWithStatic(clientId, secretKey, objectApiName, expressions, nextRecordQueryId, options)`
  - 支持游标式分页，`nextRecordQueryId` 为上一次调用返回的游标 ID，首次为
    `undefined`。

---

## 15. 其他常用工具与模块（详细）

### 15.1 CCUtils：通用工具

#### 15.1.1 获取域名 `getDomain()`

```js
const domain = $CCDK.CCUtils.getDomain();
// 示例：返回 xx.com / xx.cn / xx.com.cn / xx.net.cn 等
```

#### 15.1.2 获取当前页面类型 `getCurrentPageType()`

```js
const pageType = $CCDK.CCUtils.getCurrentPageType();
// "view"：视图页（列表页）
// "detail"：详情页
```

#### 15.1.3 表单 ID 相关（新建/编辑页）

在新建/编辑页面的客户端脚本中，`obj` 参数通常包含 `formId`，也可以通过 CCUtils
获取：

```js
// 获取最后一次打开的表单 formId
const formId = $CCDK.CCUtils.getFormId();

// 获取当前会话内所有打开表单的 formId 集合
const allFormIds = $CCDK.CCUtils.getFormId({ type: "all" });
```

#### 15.1.4 设置主表单字段值 `setFormFieldValue(option)`

> 在新建/编辑页上给主对象字段设置默认值或动态赋值，需结合客户端脚本（onLoad/onChange）。

```js
// 客户端脚本中 obj.formId 由平台注入
const formId = obj.formId;
const option = {
  formId,
  list: [
    {
      fieldKey: "name", // 字段 apiname
      value: "测试客户", // 字段值
    },
    {
      fieldKey: "khmc__c",
      value: "0013423dsdsds",
      valueName: "客户名称", // 查找字段需要 label
    },
  ],
};

$CCDK.CCUtils.setFormFieldValue(option);
```

#### 15.1.5 获取主表单字段值 `getFormFieldValue(option)`

```js
const formId = obj.formId;
const option = {
  formId,
  list: [
    { fieldKey: "name" },
    { fieldKey: "phone" },
  ],
};

const result = $CCDK.CCUtils.getFormFieldValue(option);
// 返回值包含各字段当前采集值
```

#### 15.1.6 获取主表单字段详细信息 `getFormFieldInfo(option)`

```js
const formId = obj.formId;
const option = {
  formId,
  list: [{ fieldKey: "name" }],
};

const info = $CCDK.CCUtils.getFormFieldInfo(option);
// info 中包含字段类型、label、当前值等详细信息
```

#### 15.1.7 从记录（相关列表）数据相关

在从记录新增行（addLine 型客户端脚本）中，`obj` 通常包含 `formId`、`relatedId`：

```js
const { formId, relatedId } = obj;

// 获取从记录所有数据
$CCDK.CCUtils.getRelatedInfo({ formId });

// 获取指定从记录的数据
$CCDK.CCUtils.getRelatedValue({ formId, relatedId });

// 设置从记录字段值
$CCDK.CCUtils.setRelatedValue({
  formId,
  relatedId,
  updateType: "lastLine", // "all" / "lastLine" / 指定索引
  list: [
    {
      fieldKey: "amount__c",
      value: 100,
    },
  ],
});
```

#### 15.1.8 浏览器通知 `notify(options)`

```js
// 最简单用法
$CCDK.CCUtils.notify({ title: "提示" });

// 标题 + 正文
$CCDK.CCUtils.notify({
  title: "新消息",
  body: "您有一条待办需要处理",
});

// 标题 + 正文 + 图标
$CCDK.CCUtils.notify({
  title: "系统通知",
  body: "任务已完成",
  icon: "/favicon.ico",
});
```

#### 15.1.9 标签标题闪烁 `blinkTitle(options)`

```js
// 默认提示
$CCDK.CCUtils.blinkTitle();

// 自定义文案与间隔
$CCDK.CCUtils.blinkTitle({
  message: "你有一条新消息",
  interval: 800,
});
```

---

### 15.2 CCCrypto：加解密

> 基于 AES（含 key、iv）的简单加解密工具，仅 PC 可用。

#### 15.2.1 加密 `encrypt(data, key, iv)`

```js
const cipher = $CCDK.CCCrypto.encrypt(
  { name: "zhangsan" },
  "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", // 32 字节密钥
  1, // 偏移量
);
```

#### 15.2.2 解密 `decrypt(data, key, iv)`

```js
const data = "rgTxYdmUGNelPbfoChXe5eTQqNDPxTNv..."; // 省略长密文
const result = $CCDK.CCCrypto.decrypt(
  data,
  "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  1,
);
```

---

### 15.3 CCSide：侧边工具栏

> 在 PC 端打开一个挂载自定义页面的侧边栏，如「AI 助手」「工具面板」等。

#### 15.3.1 初始化 `init(options)`

```js
$CCDK.CCSide.init({
  width: "300px",
  pageApi: "dht", // 对应自定义页面 API
});
```

#### 15.3.2 打开/关闭

```js
$CCDK.CCSide.open();
$CCDK.CCSide.close();
```

---

### 15.4 CCApplication：应用信息

#### 15.4.1 获取当前应用 `getApplicaton()`

```js
const app = $CCDK.CCApplication.getApplicaton();
// app.id：应用 id
// app.name：应用名称
// app.navigationStyle：'0' 控制台样式，'1' 标准样式
```

> `open(appId)` 处于开发中，用于在前端打开指定应用。

---

### 15.5 CCCall：电话集成

> 仅 PC 端，需与 CloudCC 后台配置的电话服务商配合使用。

#### 15.5.1 初始化电话功能 `init(id, callClient)`

```js
const callClient = {
  // 点击平台手机号、电话图标时平台会回调此方法
  call: (options) => {
    const number = options.number; // 要外呼的号码
    // 调用第三方话务 SDK 进行外呼
  },
};

const client = $CCDK.CCCall.init("abc", callClient);
// "abc" 为电话服务商唯一标识，从 CloudCC 后台「沟通渠道 → 电话」配置中获取
```

#### 15.5.2 外呼与呼叫面板

```js
// 直接发起外呼
$CCDK.CCCall.call("abc", { number: "13800000000" });

// 打开电话面板
$CCDK.CCCall.openCallPanel("abc", { number: "13800000000" });
```

---

### 15.6 CCI18n：多语言

> 在组件/页面中使用 CCDK 自带的 i18n 能力维护多语言词条。

#### 15.6.1 添加词条 `addMessages(langType, message)`

```js
// 中文
$CCDK.CCI18n.addMessages($CCDK.CCI18n.LocalEnum.ZH, {
  hello: "你好",
  test: "测试",
});

// 英文
$CCDK.CCI18n.addMessages($CCDK.CCI18n.LocalEnum.EN, {
  hello: "hello",
  test: "test",
});
```

#### 15.6.2 切换语言 `setLocale(langType)`

```js
$CCDK.CCI18n.setLocale($CCDK.CCI18n.LocalEnum.ZH); // 显示中文
$CCDK.CCI18n.setLocale($CCDK.CCI18n.LocalEnum.EN); // 显示英文
```

#### 15.6.3 获取词条 `t(key)`

```js
// 在 JS 中
const label = $CCDK.CCI18n.t("hello");

// 在 Vue 计算属性中
computed: {
  labelTest() {
    return window.$CCDK.CCI18n.t("test");
  }
}
```

---

### 15.7 CCLoading：加载遮罩

> 基于 ElementUI 的 Loading 服务，适合在组件/页面中显示「加载中」状态。

#### 15.7.1 开启 Loading

```js
const loadingInstance = Vue.prototype.$loading({
  target: document.body, // 或指定 DOM
  lock: true,
  text: "加载中...",
  background: "rgba(0, 0, 0, 0.3)",
});
```

常用配置：

- `target`：需要覆盖的 DOM 节点（DOM 对象或选择器字符串）
- `fullscreen`：是否全屏
- `lock`：是否锁定 body 滚动
- `text`：加载文字
- `background`：遮罩背景色

#### 15.7.2 关闭 Loading

```js
loadingInstance.close();
```

---