Skip to content

getting-started.cn.mdx

Latest commit

 

History

History
289 lines (237 loc) · 5.96 KB

getting-started.cn.mdx

File metadata and controls

289 lines (237 loc) · 5.96 KB
Raw
title 快速开始
description 5 分钟内构建你的第一个 ObjectStack 应用程序

ObjectStack 是协议优先的平台。@objectstack/spec 包提供了 Zod 模式和严格的 TypeScript 类型来构建有效的元数据定义。

## 初始化项目

你可以从头开始或将 ObjectStack 添加到现有的 TypeScript 项目中。

mkdir my-app
cd my-app
npm init -y
npm install typescript zod @objectstack/spec
npx tsc --init
## 定义第一个对象

创建文件 src/domains/crm/contact.object.ts。 这就是 Zod 优先定义 的强大之处。你可以获得开箱即用的自动完成和验证。

import { ObjectSchema, Field } from '@objectstack/spec';

export const Contact = ObjectSchema.create({
  name: 'contact',
  label: '联系人',
  pluralLabel: '联系人',
  icon: 'user',
  description: '与账户关联的人员',
  nameField: 'full_name',
  
  fields: {
    // 基本信息
    first_name: Field.text({ 
      label: '名', 
      required: true,
      maxLength: 100,
    }),
    
    last_name: Field.text({ 
      label: '姓', 
      required: true,
      maxLength: 100,
    }),
    
    // 公式字段 - 自动计算
    full_name: Field.formula({ 
      label: '全名',
      expression: 'CONCAT(first_name, " ", last_name)',
    }),
    
    // 联系信息
    email: Field.email({ 
      label: '电子邮件',
      unique: true,
    }),
    
    phone: Field.phone({ 
      label: '电话',
    }),
    
    // 带预定义选项的选择字段
    type: Field.select({
      label: '联系人类型',
      options: [
        { label: '客户', value: 'customer', default: true },
        { label: '合作伙伴', value: 'partner' },
        { label: '供应商', value: 'vendor' },
      ],
    }),
    
    // 与账户的关系
    account: Field.masterDetail('account', {
      label: '账户',
      required: true,
      deleteBehavior: 'cascade',
    }),
  },
  
  enable: {
    apiEnabled: true,
    trackHistory: true,
  }
});
## 添加账户对象

创建 src/domains/crm/account.object.ts 作为父对象：

import { ObjectSchema, Field } from '@objectstack/spec';

export const Account = ObjectSchema.create({
  name: 'account',
  label: '账户',
  pluralLabel: '账户',
  icon: 'building',
  nameField: 'name',
  
  fields: {
    // 自动编号字段
    account_number: Field.autonumber({
      label: '账户编号',
      format: 'ACC-{0000}',
    }),
    
    name: Field.text({ 
      label: '账户名称', 
      required: true,
      searchable: true,
      maxLength: 255,
    }),
    
    // 货币字段
    annual_revenue: Field.currency({ 
      label: '年收入',
      min: 0,
    }),
    
    // 带自定义颜色的选择字段（用于看板）
    type: Field.select({
      label: '账户类型',
      options: [
        { label: '潜在客户', value: 'prospect', color: '#FFA500', default: true },
        { label: '客户', value: 'customer', color: '#00AA00' },
        { label: '合作伙伴', value: 'partner', color: '#0000FF' },
      ],
    }),
  },
  
  enable: {
    apiEnabled: true,
    trackHistory: true,
  }
});
## 创建应用程序清单

创建 objectstack.config.ts 将对象打包到应用中：

import { defineManifest } from '@objectstack/spec';
import { Account } from './src/domains/crm/account.object';
import { Contact } from './src/domains/crm/contact.object';

export default defineManifest({
  name: 'my_crm',
  label: '我的 CRM',
  version: '1.0.0',
  description: '简单的 CRM 应用程序',
  
  objects: [Account, Contact],
  
  navigation: {
    tabs: [
      {
        label: '销售',
        items: [
          { type: 'object', object: 'account' },
          { type: 'object', object: 'contact' },
        ],
      },
    ],
  },
});
## 验证协议

创建构建脚本 src/build.ts 来验证你的定义：

import config from '../objectstack.config';

// 如果模式无效，这将抛出 ZodError
console.log(`✅ 应用 '${config.label}' 有效！`);
console.log(`📦 对象: ${config.objects.map(o => o.name).join(', ')}`);

// 导出为 JSON 供运行时使用
import fs from 'fs';
fs.writeFileSync(
  'dist/manifest.json', 
  JSON.stringify(config, null, 2)
);

运行它：

npx tsx src/build.ts
## 探索高级功能

现在你有了一个可工作的应用，探索高级功能：

1. 添加验证规则

validations: [
  {
    name: 'unique_email',
    type: 'unique',
    fields: ['email'],
    message: '电子邮件已存在',
  },
  {
    name: 'positive_revenue',
    type: 'script',
    expression: 'annual_revenue >= 0',
    message: '收入必须为正数',
  },
]

2. 添加工作流规则

workflows: [
  {
    name: 'update_last_activity',
    trigger: 'on_update',
    actions: [
      {
        type: 'field_update',
        field: 'last_activity_date',
        value: 'TODAY()',
      },
    ],
  },
]

3. 配置视图

views: {
  list: {
    type: 'grid',
    columns: ['account_number', 'name', 'type', 'annual_revenue'],
    filters: [
      { field: 'type', operator: '=', value: 'customer' }
    ],
  },
  kanban: {
    type: 'kanban',
    groupBy: 'type',
    columns: ['name', 'annual_revenue'],
  },
}
## 下一步

现在你有了有效的元数据，你可以：

  1. 探索示例：查看 CRM 示例 了解完整功能实现
  2. 学习字段类型：参见 字段类型指南 了解所有 30+ 种字段类型
  3. 构建 UI：使用 ObjectStack 运行时的元数据来生成界面
  4. 部署：推送到 ObjectStack 内核用于生产环境

其他资源：