Giao diện

API reference ​

uiSchemas resource ​

uiSchemas:getJsonSchema ​

Lấy schema tree từ UID gốc. Trả về JSON schema đầy đủ bao gồm tất cả descendants.

GET /api/uiSchemas:getJsonSchema/<x-uid>

Response:

json
{
  "data": {
    "type": "void",
    "x-uid": "p1",
    "x-component": "Page",
    "properties": {
      "grid1": {
        "type": "void",
        "x-uid": "g1",
        "x-component": "Grid",
        "properties": {
          "block1": {
            "type": "void",
            "x-uid": "b1",
            "x-component": "TableBlockProvider"
          }
        }
      }
    }
  }
}

Cache enabled — kết quả được cache theo UID. Gọi clearCache nếu cần refresh.

uiSchemas:getProperties ​

Lấy children trực tiếp (depth = 1) của schema node.

GET /api/uiSchemas:getProperties/<x-uid>

Chỉ trả về properties cấp 1, không đệ quy vào sâu hơn. Cache enabled.

uiSchemas:insert ​

Chèn schema mới vào cây. Schema có thể là nested tree (plugin tự tách thành single nodes).

POST /api/uiSchemas:insert
Body: {
  "x-uid": "parent_uid",
  "schema": {
    "type": "void",
    "x-component": "FormV2",
    "properties": {
      "field1": {
        "type": "string",
        "x-component": "Input"
      }
    }
  }
}

Plugin xử lý:

  1. Tách nested schema thành single nodes.
  2. INSERT vào uiSchemas cho mỗi node.
  3. INSERT closure paths vào uiSchemaTreePath.
  4. Trigger ServerHooks (onSelfCreate).
  5. Invalidate cache.

uiSchemas:remove ​

Xóa schema node kèm cascade tất cả descendants.

POST /api/uiSchemas:remove
Body: { "x-uid": "b1" }

Cascade xóa:

  • Tất cả descendant records trong uiSchemas.
  • Tất cả closure paths trong uiSchemaTreePath.
  • ServerHooks records trong uiSchemaServerHooks.
  • Trigger onSelfDestroy hooks.
  • Trigger removeParentsIfNoChildren nếu parent container trở nên rỗng.

uiSchemas:patch ​

Cập nhật partial schema. Merge vào schema hiện có (không replace toàn bộ).

POST /api/uiSchemas:patch
Body: {
  "x-uid": "b1",
  "x-component-props": {
    "title": "Bảng đơn hàng (cập nhật)"
  }
}

uiSchemas:batchPatch ​

Cập nhật nhiều schema nodes cùng lúc trong một atomic transaction.

POST /api/uiSchemas:batchPatch
Body: {
  "schemas": [
    { "x-uid": "c1", "title": "Tên khách hàng" },
    { "x-uid": "c2", "title": "Trạng thái" }
  ]
}

Nếu bất kỳ patch nào fail, toàn bộ batch rollback.

uiSchemas:insertAdjacent ​

Chèn schema ở vị trí cụ thể so với node tham chiếu.

POST /api/uiSchemas:insertAdjacent/<x-uid>?position=afterEnd
Body: {
  "schema": {
    "type": "void",
    "x-component": "CardItem"
  }
}
PositionMô tả
beforeBeginTrước node tham chiếu (cùng parent)
afterBeginĐầu danh sách children của node
beforeEndCuối danh sách children của node
afterEndSau node tham chiếu (cùng parent)

uiSchemas:clearAncestor ​

Detach node khỏi cây — xóa ancestor links nhưng giữ nguyên node và descendants.

POST /api/uiSchemas:clearAncestor
Body: { "x-uid": "b1" }

Node trở thành "root" riêng — vẫn tồn tại trong DB nhưng không thuộc tree nào.

uiSchemas:clearCache ​

Xóa cache schema cho UID cụ thể hoặc toàn bộ.

POST /api/uiSchemas:clearCache
Body: { "uid": "p1" }

Bỏ uid để xóa toàn bộ cache.

uiSchemas:saveAsTemplate ​

Snapshot subtree thành template tái sử dụng.

POST /api/uiSchemas:saveAsTemplate
Body: {
  "x-uid": "b1",
  "key": "order-table-template",
  "name": "Bảng đơn hàng mẫu",
  "componentName": "TableBlockProvider",
  "collectionName": "orders",
  "dataSourceKey": "main"
}

uiSchemaTemplates resource ​

uiSchemaTemplates:list ​

Danh sách template đã lưu.

GET /api/uiSchemaTemplates:list?filter[componentName]=TableBlockProvider

uiSchemaTemplates:get ​

Chi tiết template theo key.

GET /api/uiSchemaTemplates:get?filterByTk=order-table-template

Ví dụ sử dụng ​

Tạo page schema với block ​

typescript
await agent.resource('uiSchemas').insert({
  values: {
    'x-uid': 'page_root',
    schema: {
      type: 'void',
      'x-component': 'Page',
      properties: {
        grid1: {
          type: 'void',
          'x-component': 'Grid',
          properties: {
            table1: {
              type: 'void',
              'x-component': 'TableBlockProvider',
              'x-component-props': { collection: 'orders' },
            },
          },
        },
      },
    },
  },
});

Patch title của một column ​

typescript
await agent.resource('uiSchemas').patch({
  values: {
    'x-uid': 'col_name',
    title: 'Tên khách hàng (mới)',
  },
});

Lưu block thành template ​

typescript
await agent.resource('uiSchemas').saveAsTemplate({
  values: {
    'x-uid': 'table1',
    key: 'tpl_order_table',
    name: 'Order Table Template',
    componentName: 'TableBlockProvider',
    collectionName: 'orders',
  },
});