# @collidor/struct 中文文档

规范地址：https://npmcn.com/package/%40collidor/struct/

版本：1\.1\.2
npm 元数据更新时间：2026-11-05T15:43:31.315Z
中文译文更新时间：2026-11-10T11:08:25.936Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40collidor/struct
原文对照：https://npmcn.com/package/%40collidor/struct/?lang=original
项目主页：https://github.com/collidor/struct#readme
源码仓库：https://github.com/collidor/struct

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：636 kB，109 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：zod ^3\.0\.0 \|\| ^4\.0\.0，vee-validate ^4\.0\.0
- 首次发布：2026-10-03T16:47:43.232Z
- 最新版本发布：2026-11-05T15:43:30.959Z
- 近 30 天下载量：8079（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

有标准Schema、JSON Schema、Zod interop、Axon图形端口打字和 Vee-Validate 格式生成的模块数据结构构建器

## 安装

```sh
npm install @collidor/struct
```

也可以使用：`pnpm add @collidor/struct`、`yarn add @collidor/struct`、`bun add @collidor/struct`

## README

# @ collidor/ struct

具有标准Schema兼容性的模块数据结构构建器,JSON Schema / Zod双向桥,Axon图端口打字,和Vee-Validate形式生成.

## 特征

-   📐 **标准Schema V1 客户端**:直接与现代形式,验证,API库相通.
-   🔄 **双向桥**: 无损失相交 **佐德语Name** (单位:千美元)`toZod`, (中文(简体) ), `fromZod`和 **杰森·斯克马** (单位:千美元)`toJSONSchema`, (中文(简体) ), `fromJSONSchema`) (中文(简体) ).
-   ⚡ **Axon 端口子打字**: 完整的图表数据类型描述器绘图和子类型相容性检查器(`isAssignable`) (中文(简体) ).
-   📝 **动态 UI 格式生成**: 自动字段布局、部件推论和交互式窗体构建器(`StructBuilder`, (中文(简体) ), `getFormFields`) (中文(简体) ).
-   🗄️ **存储和 DDL 迁移**:SQLite/SQL后端的Schema DDL生成和交易迁移.
-   🧮 **计算属性**: 具有AST依赖性地貌分辨率的安全内膜公式评价.

## 安装

### 德诺/JSR

```bash
deno add jsr:@collidor/struct
```

### 节点/ npm/ pnpm/ Bun

```bash
npx jsr add @collidor/struct
# or
pnpm dlx jsr add @collidor/struct
# or
bunx jsr add @collidor/struct
```

## 快速启动

```typescript
import { s } from "@collidor/struct";

// Define a schema
const UserSchema = s.struct({
  id: s.string().uuid(),
  name: s.string().min(2).max(50),
  email: s.string().email(),
  age: s.number().positive().optional(),
  tags: s.array(s.string()).default([]),
});

// Validate synchronous or asynchronous
const result = UserSchema.safeParse({
  id: "123e4567-e89b-12d3-a456-426614174000",
  name: "Alykam",
  email: "alykam@example.com",
});

if (result.success) {
  console.log("Validated user:", result.data);
} else {
  console.error("Validation issues:", result.issues);
}
```

## 统一窗体构建器( E)`@collidor/struct/form`(中文(简体) )

这个 `@collidor/struct/form` 二次导出统一空间布局容器、非数据 UI 装饰器、有条件渲染以及直接在结构定义内收集视图模式:

```typescript
import { f } from "@collidor/struct/form";

const OnboardingForm = f.struct({
  banner: f.alert({
    title: "Welcome",
    message: "Fill in your details below",
    tone: "info",
  }),

  // Put two inputs on the same line
  nameRow: f.row({
    firstName: f.string().min(2),
    lastName: f.string().min(2),
  }, { gap: "1rem" }),

  accountType: f.enum(["personal", "business"] as const).default("personal"),

  // Conditional branch (validation bypassed when hidden)
  companyInfo: f.when('accountType == "business"', {
    companyName: f.string(),
    vatId: f.string(),
  }),

  // Collection view modes (asTable, asList, asCards, asTags)
  skills: f.array(f.string()).asTags(),
  submitBtn: f.button({ label: "Create Account", action: "submit" }),
});

// Flat data model: UI-only nodes stripped, layout containers flattened!
const validated = OnboardingForm.parse({
  firstName: "Ada",
  lastName: "Lovelace",
  accountType: "personal",
  skills: ["computing", "math"],
});

// Framework-agnostic Headless Form Controller
const controller = f.createController(OnboardingForm, {
  initialValues: validated,
  onSubmit: (values) => console.log("Submitted:", values),
});
```

## Zod & JSON Schema 接口

```typescript
import { s, toZod, fromZod, toJSONSchema, fromJSONSchema } from "@collidor/struct";
import { z } from "zod";

// Convert struct to Zod
const zodUser = toZod(UserSchema);

// Convert Zod to struct
const zodSchema = z.object({ count: z.number().int().positive() });
const structFromZod = fromZod(zodSchema);

// JSON Schema export
const jsonSchema = toJSONSchema(UserSchema);
```

## 许可证

麻省理工学院 [阿利坎·伯德崎](https://alykam.com/)

## 常见问题

### @collidor/struct 是什么？

有标准Schema、JSON Schema、Zod interop、Axon图形端口打字和 Vee-Validate 格式生成的模块数据结构构建器

### 如何安装 @collidor/struct？

在项目目录运行 npm install @collidor/struct，或使用 pnpm add / yarn add / bun add。

### @collidor/struct 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @collidor/struct 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @collidor/struct 可以商用吗？

@collidor/struct 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @collidor/struct 的下载量有多少？

根据 npm 官方下载统计，@collidor/struct 在 2026/10/11 – 2026/11/09 这 30 天内被下载 8,079 次，日均约 269 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @collidor/struct 还在维护吗？

最新版本 1\.1\.2 发布于 2026/11/05（4 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/10/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。