# 业务操作脚本（JS 模式）context API 参考

> 适用：表单业务操作 `fdType=3` + `fdViewType=5`（平台「脚本模式」）。
> 结论来源：sys-modeling 前端源码（MK-PaaS，`frontend/sys-modeling`）。
> **重要**：除 `fdOprId` / `fdIds` / `fdBtnCfg` / `destroyLoading` 是显式注入外，
> 其余字段来自组件内部 props 的浅拷贝，**不是公开契约**，平台升级可能变化——使用前请做 `typeof` 兜底。

## 1. 执行机制

点击「脚本模式」按钮后，前端先调 `sysModelingOperation` 相关接口拿到操作配置，再执行脚本：

```js
// desktop/operation/other.ts（移动端 mobile/operation/other.ts 同构）
new Function('context', model.fdCfg?.fdJavaScript)({
  ...context,          // 列表页传入的上下文（浅拷贝，见第 3 节）
  fdOprId: operation.id,
  fdIds: params['fdIds'],
  fdBtnCfg: model.fdCfg,
  destroyLoading,      // 关闭「执行中...」提示
})
```

关键点：

1. 脚本在**全局作用域**求值，可直接用 `window.mk`、`window.MKXFORM`、`fetch` 等页面全局对象；
2. 脚本抛错会被前端 `try/catch` 吞掉（仅 `console.error`），页面只关闭 loading——**错误不会提示用户**，
   脚本内部必须自己 try/catch 并给出可见反馈；
3. 平台**不会**在脚本执行后自动刷新列表（只有 AI 能力分支会 `refresh()`），需要刷新就自己调；
4. 脚本里调用 `context.destroyLoading()` 后，前端检测到即不再重复关闭；不调用则由前端关闭（无参数执行完也关）。

## 2. 显式注入字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `context.fdOprId` | `string` | 当前业务操作 id |
| `context.fdIds` | `string[] \| undefined` | 选中/当前行 id。**仅** `operation.selected === true` 时赋值：行内按钮、标准行操作；工具栏按钮通常为 `undefined` |
| `context.fdBtnCfg` | `object` | 操作配置（后端返回的 `fdCfg` 解析结果，含 `fdViewType` / `fdJavaScript` 等） |
| `context.destroyLoading` | `() => void` | 关闭「执行中...」提示并复位按钮 loading |

## 3. 列表页上下文（desktop）

`context` 由列表页 `useListOperations` 组装（`components/list-core/hooks/useListOperations.ts`），
是 `content.tsx` 传入 props 的浅拷贝 + 若干选中态字段。

### 3.1 选中数据

| 字段 | 类型 | 说明 |
|---|---|---|
| `selectedId` | `string[]` | 勾选行的 `fd_id` 数组（组件 state，工具栏按钮场景） |
| `docId` | `string \| undefined` | 行内按钮：当前行 id（= `operation.selectedIds[0]`） |
| `fdIds` | `string[] \| undefined` | 见第 2 节；行内按钮/标准行操作才有 |
| `setSelectedId` | `(ids: string[]) => void` | 设置勾选行 |
| `setSelectedDocs` | `(docs: any[]) => void` | 设置勾选行的完整数据 |

**取值优先级建议**：`fdIds`（行内按钮）→ `selectedId`（工具栏勾选）→ `docId`（兜底）。

> 坑：`selectedId: selectedId || selectedIds`，空数组 `[]` 是 truthy——行内按钮点击时
> `selectedId` 往往就是 `[]`，此时必须用 `docId` / `fdIds`。

### 3.2 列表数据

| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | `any[]` | 当前页数据数组（= `$$contentviewProps.data`，行字段 `fd_id`） |
| `$$contentviewProps.data` | `any[]` | 同上；`$$contentviewProps` 还含 `refresh` / `query` / `queryChange` / `history` |
| `xlistRuntimeRef.current.getData()` | `() => { content: any[] }` | 列表运行时数据（**类型未声明**，运行时存在，需兜底） |

### 3.3 刷新与查询

| 入口 | 说明 |
|---|---|
| `context.refresh(query?)` | 推荐。等价 `xlistRuntimeRef.current.loadData(query)` |
| `context.$$contentviewProps.refresh(query?)` | 同上（列表页透传的同一个函数） |
| `context.cacheListRef.current.refresh(query?)` | 列表页把 `refresh` 缓存在这里，供跨组件/iframe 使用 |
| `context.xlistRuntimeRef.current.loadData(query?)` | 最底层；支持传对象或函数式 updater |
| `context.$$contentviewProps.queryChange(newQuery)` | 在现有 query 上合并后重载：`loadData(q => ({...q, ...newQuery}))` |
| `context.cacheListRef.current.queryChange` | 同上（缓存副本） |

### 3.4 视图 / 权限 / 路由上下文

| 字段 | 说明 |
|---|---|
| `formId` | 表单 id |
| `listviewId` | 列表视图 id |
| `fdRightGroupId` | 当前权限组 id |
| `appId` / `appCode` | 应用 id / 编码 |
| `fdCategoryModelCode` / `fdCategoryType` / `fdCategoryId` | 分类表单相关 |
| `menuId` / `baseUrl` | 菜单与路由前缀 |
| `fdOpenMode` / `drawerOptions` | 打开方式（`self`/`drawer`/`_blank`）与抽屉配置 |
| `isInDrawer` | 当前是否在抽屉内 |
| `templateId` / `commonIncParams` / `localQuery` / `mainTable` | 模板、公共入参、本地查询、主表标识 |
| `params` | 外部调用 `operations.execute(op, params)` 时传入的第二个参数 |
| `dispatch` | 通用弹窗 reducer：`dispatch({type:'modalProps', payload:{...}})`（内部状态，不建议依赖） |
| `setDoingOperation` | `(v: boolean) => void`，切换按钮「执行中」状态 |

### 3.5 工具栏按钮 vs 行内按钮

| 场景 | `selected` | `fdIds` | `docId` | `selectedId` |
|---|---|---|---|---|
| 列表工具栏按钮 | 通常 `undefined` | `undefined` | `undefined` | 勾选行数组（可能 `[]`） |
| 行内右侧按钮 | `true` | `[当前行 id]` | 当前行 id | 通常 `[]` |
| 外部 `operations.execute` | 取决于调用方 | 需自己传 | 需自己传 | 取决于调用方 |

> 平台配置的「勾选数据」（`fdConfig.fdListViewIdValid`）在脚本模式下**不会**转成 `selected`，
> 也不会触发「请选择数据」校验——脚本必须自己判断并提示。

## 4. 全局能力（window）

| API | 说明 |
|---|---|
| `mk.openLink({ url, target, drawerOptions, forceTarget })` | 打开页面：`target` 取 `self` / `drawer` / `_blank` |
| `mk.normalizeUrl('sys://user/sys-modeling/<path>')` | 内部路由转可访问地址（业务操作的 `goto` 用它） |
| `mk.getSysConfig(key)` | `modulesUrlPrefix` / `apiUrlPrefix` / `currentUser` / `platform` / `standalone` 等 |
| `mk.emit(event, payload)` / `mk.on` / `mk.off` | 事件总线（如 `mk.emit('CHANGETAGSS')`、`mk.emit(MkModelingEventTypes.PageListStateChange, {})`） |
| `mk.userStore` | 全局 key-value（`mk.userStore.set({ key, value })` / `get`） |
| `window.MKXFORM` | 列表页已初始化（`components/list-core/components/content-area.tsx`）：`tableModal` / `modal` / `HTMLModal`；表单上下文还有 `setValue`/`getValue` 等（见 `mkxform-api.md`） |
| `fetch` / `Blob` / `navigator.clipboard` / `window.open` | 标准浏览器能力，可自行调接口、导出文件 |

### 4.1 跨窗口 / iframe

列表页监听 `message`（`window` 与 `window.parent`）：

| 事件名 | 效果 |
|---|---|
| `mk-refresh-opener`（`ModelingDrawerViewEvents.RefreshPage`） | 触发列表刷新（`cacheListRef.current.refresh()`） |
| `PageInfo` / `Clear` / `TurnPage` | 分页信息交换 / 清缓存 / 翻页（列表页与抽屉 iframe 之间） |

```js
window.parent.postMessage({ eventType: 'mk-refresh-opener' }, '*')
```

## 5. 常用片段

### 5.1 读取选中数据 + 兜底

```js
function resolveRows(ctx) {
  var ids = (Array.isArray(ctx.fdIds) && ctx.fdIds.length ? ctx.fdIds : null) ||
            (Array.isArray(ctx.selectedId) && ctx.selectedId.length ? ctx.selectedId : null) ||
            (ctx.docId ? [ctx.docId] : [])
  var list = (ctx.$$contentviewProps && ctx.$$contentviewProps.data) || ctx.data || []
  if (!list.length && ctx.xlistRuntimeRef && ctx.xlistRuntimeRef.current) {
    try { list = (ctx.xlistRuntimeRef.current.getData() || {}).content || [] } catch (e) { list = [] }
  }
  return list.filter(function (row) { return ids.indexOf(row.fd_id || row.fdId) > -1 })
}
```

### 5.2 刷新列表（多级兜底）

```js
function refreshList(query) {
  var c = context
  try {
    if (typeof c.refresh === 'function') return c.refresh(query)
    if (c.$$contentviewProps && typeof c.$$contentviewProps.refresh === 'function')
      return c.$$contentviewProps.refresh(query)
    if (c.cacheListRef && c.cacheListRef.current && typeof c.cacheListRef.current.refresh === 'function')
      return c.cacheListRef.current.refresh(query)
    if (c.xlistRuntimeRef && c.xlistRuntimeRef.current && typeof c.xlistRuntimeRef.current.loadData === 'function')
      return c.xlistRuntimeRef.current.loadData(query)
  } catch (e) {
    console.warn('[script] refresh failed', e)
  }
}
```

### 5.3 打开页面 / 抽屉

```js
window.mk.openLink({
  url: window.mk.normalizeUrl('sys://user/sys-modeling/add/' + context.formId),
  target: context.fdOpenMode || '_blank',
  drawerOptions: context.drawerOptions,
})
```

### 5.4 批量调接口后刷新

```js
fetch(window.mk.getSysConfig('apiUrlPrefix') + '/sys-modeling/<接口路径>', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ fdIds: context.selectedId }),
})
  .then(function (r) { return r.json() })
  .then(function () { refreshList(); context.setSelectedId([]); context.destroyLoading() })
  .catch(function (e) { console.error(e); context.destroyLoading() })
```

## 6. 移动端差异

`mobile/operation/other.ts` 同样是 `new Function('context', script)({ ...context, fdIds, destroyLoading })`：

- 可靠可用的：`fdOprId`、`fdIds`、`fdBtnCfg`、`destroyLoading`、`refresh`（查看/编辑页传的是整页 `refreshPage`）；
- **不要依赖** `xlistRuntimeRef` / `$$contentviewProps` / `cacheListRef`（PC 列表专有），移动端列表是 `m-list-view`；
- 移动端 `refresh()` 是整页重渲染，不是 `loadData(query)`。

## 7. 已知边界与坑

1. **没有** `context.selectRow`、`context.requestData`、`context.showAddPopup`、`context.queryChange`（后者只在 `$$contentviewProps` 里）。
2. `callback` / `lcodeIncParams` / `defaultTemplateData` / `detailDataRowFilterOrder` 在列表页点击场景为 `undefined`（列表页未传）。
3. `getData()` 未出现在 `IXListRuntimeRef` 类型声明中，仅运行时存在。
4. 脚本异常被静默吞掉，务必自己 try/catch + 提示 + `destroyLoading()`。
5. 刷新后如需清空勾选：`context.setSelectedId([])`。
6. 不要直接修改 `$$contentviewProps.data`（不持久化，且与组件 state 不一致），写操作走后端接口。
7. 调试：脚本里 `console.log(context)` 后在浏览器控制台查看完整字段；`localStorage.getItem('mk-debugger') === 'true'` 时平台会打印部分调试信息。

## 8. 源码索引（核对版本用）

| 内容 | 位置（sys-modeling/src） |
|---|---|
| 脚本执行入口（PC） | `desktop/operation/other.ts` |
| 脚本执行入口（移动） | `mobile/operation/other.ts` |
| context 组装 | `components/list-core/hooks/useListOperations.ts` |
| 列表页 props / refresh | `desktop/pages/list/index.ts` |
| 列表内容区 / window.MKXFORM | `components/list-core/components/content.tsx`、`content-area.tsx` |
| 按钮点击 / 行内按钮 | `components/view-config/utils/operationsFun.tsx` |
| 统一执行入口 | `desktop/operation/execute.ts` |
