CIC 标准库 (Component Interaction Configuration)

​CIC（Common Intermediate Configuration，大屏可视化交换格式）​​ 是一套面向可视化大屏项目的 ​​ 结构化序列化标准 ​​，聚焦于定义中间层的通用配置规则。其核心目标是解决大屏项目在跨平台迁移、批量导入/导出及版本化管理中的关键痛点——通过 ​​ 标准化数据格式、组件交互逻辑与资源引用方式 ​​，赋予大屏内容“一次创建，多端复用”的序列化能力，系统性解决多组件协作、跨环境一致性及可扩展性难题。本仓库提供了该协议的 TypeScript 类型定义、JSON Schema 校验文件以及核心 SDK 工具库。

1. 简介

提供 CIC 标准的 TypeScript 类型与 SDK，支持 JSON Schema 校验、页面/组件/数据源等核心能力，适用于发布后的使用者。

2. SDK 使用指南

SDK 提供了操作 CIC 标准的常用工具方法，现已重构为面向对象的 CICSDK 类，内置 Ajv 引擎进行全量 JSON Schema 校验，并支持 Vite 构建与 Tree-shaking。

安装与引入

推荐使用 pnpm 安装依赖：

pnpm add @anov/cic-standard-sdk

import { CICSDK } from '@anov/cic-standard-sdk'
import  type { CICConfig, ComponentInstance, DataSourceItem, CICPage, Meta, Layout, Registry, Variables, Dependency, ICICSDK } from '@anov/cic-standard-sdk';

const config: CICConfig = { ... };
const sdk = new CICSDK(config); // 实例化时自动执行 Schema 校验

常用 API

1. 验证配置

SDK 集成了完整的 JSON Schema (Draft-07)，可验证字段类型、必填项、枚举值等。

// 静态方法校验（返回中文化错误数组）
const res = CICSDK.validateCIC(myConfig)
if (!res.ok) {
  console.error('配置校验失败:', res.errors)
  // 示例: [{ path: '/version', message: '缺少必填字段：version' }]
}

// 实例化时自动校验，失败抛出异常
try {
  const sdk = new CICSDK(myConfig)
} catch (e) {
  console.error(e.message)
}

2. 导入/导出配置

// 从 JSON 字符串导入为 CICConfig 对象
const rImport = CICSDK.importCIC(JSON.stringify(myConfig))
if (rImport.ok) {
  const cfg = rImport.value
}

// 从路径或 URL 导入（异步，兼容浏览器）
// - 支持相对路径（同源）：'./examples/full-demo.json'、'/examples/full-demo.json'
// - 支持 http(s) URL：'https://host/examples/full-demo.json'
// - 不支持 file://（请使用同源路径或 http(s)）
const rImportPath = await CICSDK.importCICAsync('/examples/full-demo.json')
if (rImportPath.ok) {
  const cfg2 = rImportPath.value
}

// 将 CICConfig 导出为稳定字段顺序的 JSON 字符串
const rExport = CICSDK.exportCIC(myConfig)
if (rExport.ok) {
  console.log(rExport.value) // string
}

2. 查找组件

// 按 ID 查找（支持跨页面）
const comp = sdk.findComponent('comp_btn_01')
if (comp) {
  console.log('找到组件:', comp.role)
}

// 查找组件所属页面
const page = sdk.findPageByComponent('comp_btn_01')
console.log('所在页面:', page?.id)

3. 获取变量值（自动处理作用域）

// 优先查找组件级 -> 页面级 -> 全局
const val = sdk.getVariable({ pageId: 'p1', componentId: 'c1' }, 'theme')

// 通过引用字符串获取
const val2 = sdk.getVariableByRef('global.theme')

4. 遍历组件树

// 遍历整个配置的所有组件
sdk.walkComponents((comp, page, parent) => {
  console.log(`遍历到: ${comp.id} (页面: ${page.id})`)
  // 返回 false 可停止遍历
  return true
})

5. 静态工具

生成器 API（严格校验 + 规范化）

• createDataSource/validateDataSource/normalizeDataSource（sdk/generators/dataSource.ts）
• createComponent/validateComponent/normalizeComponent（sdk/generators/component.ts）
• createPage/validatePage/normalizePage（sdk/generators/page.ts）
• createMeta/validateMeta/normalizeMeta（sdk/generators/meta.ts）
• createLayout/validateLayout/normalizeLayout（sdk/generators/meta.ts）
• createVariables/validateVariables/normalizeVariables（sdk/generators/variables.ts）
• createDependency/validateDependency/normalizeDependency（sdk/generators/dependency.ts）
• createRegistryComponent/validateRegistryComponent/normalizeRegistryComponent（sdk/generators/registry.ts）

所有生成器返回统一 Result<T>：{ ok: boolean; value?: T; errors?: any[] }。normalizeX 在校验失败时抛出错误，方便在构建或运行时快速失败。

// 解析路径取值
const val = CICSDK.getValueByPath(someObj, 'a.b[0].c', 'default')

// 深度遍历组件树片段
CICSDK.traverseTree(someComponent, c => {
  console.log(c.id)
})

3. 构建与类型

构建产物

• dist/cic-sdk.es.js（ESM）
• dist/cic-sdk.cjs.js（CJS）
• dist/cic-sdk.umd.js（UMD）
• 类型声明：dist/sdk/CICSDK.d.ts

package.json 设置了 sideEffects: false 并使用 exports 指定导入/require 入口，方便 Tree‑shaking。

4. JSON Schema 校验

schema/cic.schema.json 提供了完整的协议约束。

报错与排查

• Ajv 错误输出包含 instancePath：根据路径定位到具体字段（如 /pages/0/components/1/role must be equal to constant）。
• 组件判别联合：view 必须提供 component；container 必须提供 children；logic 必须提供 component（LogicRef）。
• 数值字段：如 pollInterval/timeout 必须为数字；生成器在 defaults 指定时会注入确定性默认。

最佳实践

• 严格模式：默认不做隐式容错，缺失必填即报错；通过 options.defaults 明确提供默认值。
• 按需引入：仅从 CICSDK 静态导出使用所需生成器函数，减少打包体积。
• ID 规范：通过生成器的 generateId 自动生成 uuid，避免冲突。

5. 许可与版本

• 语义化版本（SemVer）发布
• 请在 issue 中反馈使用问题与建议