diff --git a/docs/en-US/api/actions.md b/docs/en-US/api/actions.md index c752fc74e..eb644c364 100644 --- a/docs/en-US/api/actions.md +++ b/docs/en-US/api/actions.md @@ -1,8 +1,8 @@ -# 内置常用资源操作 +# Built-in Common Resource Actions -## 概览 +## Overview -针对常用的 CRUD 等数据资源的操作，NocoBase 内置了对应操作方法，并通过数据表资源自动映射相关的操作。 +NocoBase has built-in operation methods for commonly used actions of data resources, such as CRUD, and automatically maps related actions through data table resources. ```javascript import { Application } from "@nocobase/server"; @@ -12,36 +12,34 @@ const app = new Application({ dialect: 'sqlite', storage: './db.sqlite', }, - registerActions: true // 注册内置资源操作，默认为 True + registerActions: true // Register built-in resource actions, true by default }); ``` +Built-in actions are registered to the `resourcer` instance in `application`. Generally, built-in actions are not called directly unless you need to extend the default action, then you can call the default method within a custom action method. -内置的操作方法都是注册在 `application` 中的 `resourcer` 实例上。 -通常情况下无需直接调用内置的 action 方法，在需要扩展默认操作行为时，可以在自定义的操作方法内调用默认方法。 - -## 资源操作 +## Resource Actions ### `list()` -获取数据列表。对应资源操作的 URL 为 `GET /api/:list`。 +Get a list of data. The URL for the corresponding resource action is `GET /api/:list`. -**参数** +**Parameter** -| 参数名 | 类型 | 默认值 | 描述 | +| Name | Type | Default | Description | | --- | --- | --- | --- | -| `filter` | `Filter` | - | 过滤参数 | -| `fields` | `string[]` | - | 要获取的字段 | -| `except` | `string[]` | - | 要排除的字段 | -| `appends` | `string[]` | - | 要附加的关系字段 | -| `sort` | `string[]` | - | 排序参数 | -| `page` | `number` | 1 | 分页 | -| `pageSize` | `number` | 20 | 每页数据条数 | +| `filter` | `Filter` | - | Filtering parameter | +| `fields` | `string[]` | - | Fields to get | +| `except` | `string[]` | - | Fields to exclude | +| `appends` | `string[]` | - | Association fields to append | +| `sort` | `string[]` | - | Sorting parameter | +| `page` | `number` | 1 | Page break | +| `pageSize` | `number` | 20 | Size per page | -**示例** +**Example** -当需要提供一个查询数据列表的接口，但不是默认以 JSON 格式输出时，可以基于内置默认方法进行扩展： +When there is a need to provide an interface for querying a list of data that is not output in JSON format by default, it can be extended based on the built-in default method: ```ts import actions from '@nocobase/actions'; @@ -64,7 +62,7 @@ app.actions({ }); ``` -请求示例，将获得 CSV 格式文件的返回： +Example of a request that will get a file in CSV format: ```shell curl -X GET http://localhost:13000/api/books:list @@ -72,24 +70,24 @@ curl -X GET http://localhost:13000/api/books:list ### `get()` -获取单条数据。对应资源操作的 URL 为 `GET /api/:get`。 +Get a single piece of data. The URL for the corresponding resource action is `GET /api/:get`. -**参数** +**Parameter** -| 参数名 | 类型 | 默认值 | 描述 | +| Name | Type | Default | Description | | --- | --- | --- | --- | -| `filterByTk` | `number \| string` | - | 过滤主键 | -| `filter` | `Filter` | - | 过滤参数 | -| `fields` | `string[]` | - | 要获取的字段 | -| `except` | `string[]` | - | 要排除的字段 | -| `appends` | `string[]` | - | 要附加的关系字段 | -| `sort` | `string[]` | - | 排序参数 | -| `page` | `number` | 1 | 分页 | -| `pageSize` | `number` | 20 | 每页数据条数 | +| `filterByTk` | `number \| string` | - | Filtering primary key | +| `filter` | `Filter` | - | Filtering parameter | +| `fields` | `string[]` | - | Fields to get | +| `except` | `string[]` | - | Fields to exclude | +| `appends` | `string[]` | - | Association fields to append | +| `sort` | `string[]` | - | Sorting parameter | +| `page` | `number` | 1 | Page break | +| `pageSize` | `number` | 20 | Size per page | -**示例** +**Example** -基于 NocoBase 内置的文件管理插件，可以扩展当客户端请求以资源标识下载一个文件时，返回文件流： +Extend the build-in file management plugin of NocoBase to return file stream when the client requests to download a file with the resource identifier: ```ts import path from 'path'; @@ -124,7 +122,7 @@ app.actions({ }); ``` -请求示例，将获得文件流的返回： +Example request that will get the file stream: ```shell curl -X GET -H "Accept: application/octet-stream" http://localhost:13000/api/attachments:get?filterByTk=1 @@ -132,17 +130,17 @@ curl -X GET -H "Accept: application/octet-stream" http://localhost:13000/api/att ### `create()` -创建单条数据。对应资源操作的 URL 为 `POST /api/:create`。 +Create a single piece of data. The URL for the corresponding resource action is `POST /api/:create`. -**参数** +**Parameter** -| 参数名 | 类型 | 默认值 | 描述 | +| Name | Type | Default | Description | | --- | --- | --- | --- | -| `values` | `Object` | - | 要创建的数据 | +| `values` | `Object` | - | The data to create | -**示例** +**Example** -类似文件管理插件，创建带有二进制内容的数据作为上传文件的附件： +Create data with binary content as attachment to the uploaded file, it is similar to the file management plugin: ```ts import multer from '@koa/multer'; @@ -158,7 +156,7 @@ app.actions({ return ctx.throw(406); } - // 文件保存处理仅用 multer() 作为示例，不代表完整的逻辑 + // Only use multer() as example here to save and process file, it does not represent the full logic multer().single('file')(ctx, async () => { const { file, body } = ctx.request; const { filename, mimetype, size, path } = file; @@ -179,33 +177,33 @@ app.actions({ }); ``` -请求示例，可以创建文件表的普通数据，也可以含附件一起提交： +Example request to create plain data for a file table, you can submit it with an attachment: ```shell -# 仅创建普通数据 +# Create plain data only curl -X POST -H "Content-Type: application/json" -d '{"filename": "some-file.txt", "mimetype": "text/plain", "size": 5, "url": "https://cdn.yourdomain.com/some-file.txt"}' "http://localhost:13000/api/files:create" -# 含附件一起提交 +# Submit with attachment curl -X POST -F "file=@/path/to/some-file.txt" -F 'meta={"length": 100}' "http://localhost:13000/api/files:create" ``` ### `update()` -更新一条或多条数据。对应的 URL 为 `PUT /api/:update`。 +Update one or more pieces of data. The corresponding URL is `PUT /api/:update`. -**参数** +**Parameter** -| 参数名 | 类型 | 默认值 | 描述 | +| Name | Type | Default | Description | | --- | --- | --- | --- | -| `filter` | `Filter` | - | 过滤参数 | -| `filterByTk` | `number \| string` | - | 过滤主键 | -| `values` | `Object` | - | 更新数据值 | +| `filter` | `Filter` | - | Filtering parameter | +| `filterByTk` | `number \| string` | - | Filtering primary key | +| `values` | `Object` | - | Data values to update | -注：参数中的 `filter` 和 `filterByTk` 至少提供一项。 +Note: Either or both `filter` or `filterByTk` should be provided. -**示例** +**Example** -类似 `create()` 的例子，更新文件记录可以扩展为可携带二进制内容的数据作为更新的文件： +Similar to the example of `create()`, you can extend updating file record to a file that carries data with binary content: ```ts import multer from '@koa/multer'; @@ -221,7 +219,7 @@ app.actions({ return ctx.throw(406); } - // 文件保存处理仅用 multer() 作为示例，不代表完整的逻辑 + // Only use multer() as example here to save and process file, it does not represent the full logic multer().single('file')(ctx, async () => { const { file, body } = ctx.request; const { filename, mimetype, size, path } = file; @@ -242,32 +240,32 @@ app.actions({ }); ``` -请求示例，可以创建文件表的普通数据，也可以含附件一起提交： +Example request to create plain data for a file table, you can submit it with an attachment: ```shell -# 仅创建普通数据 +# Create plain data only curl -X PUT -H "Content-Type: application/json" -d '{"filename": "some-file.txt", "mimetype": "text/plain", "size": 5, "url": "https://cdn.yourdomain.com/some-file.txt"}' "http://localhost:13000/api/files:update" -# 含附件一起提交 +# Submit with attachment curl -X PUT -F "file=@/path/to/some-file.txt" -F 'meta={"length": 100}' "http://localhost:13000/api/files:update" ``` ### `destroy()` -删除一条或多条数据。对应的 URL 为 `DELETE /api/:destroy`。 +Delete one or more pieces of data. The corresponding URL is `DELETE /api/:destroy`. -**参数** +**Parameter** -| 参数名 | 类型 | 默认值 | 描述 | +| Name | Type | Default | Description | | --- | --- | --- | --- | -| `filter` | `Filter` | - | 过滤参数 | -| `filterByTk` | `number \| string` | - | 过滤主键 | +| `filter` | `Filter` | - | Filtering parameter | +| `filterByTk` | `number \| string` | - | Filtering primary key | -注：参数中的 `filter` 和 `filterByTk` 至少提供一项。 +Note: Either or both `filter` or `filterByTk` should be provided. -**示例** +**Example** -类似对文件管理插件扩展一个删除文件数据也需要同时删除对应文件的操作处理： +Similar to the file management plug-in extension, a deletion of file data also requires the deletion of the corresponding file operation processing simultaneously: ```ts import actions from '@nocobase/actions'; @@ -300,57 +298,60 @@ app.actions({ ``` ### `move()` -对应的 URL 为 `POST /api/:move`。 -此方法用于移动数据，调整数据的排序。例如在页面中，拖拽一个元素到另一个元素的上方或下方，可调用此方法实现顺序调整。 +The corresponding URL is `POST /api/:move`. -**参数** +This method is used to move data and adjust the order of data. For example, if you drag an element above or below another element in a page, you can call this method to achieve order adjustment. -| 参数名 | 类型 | 默认值 | 描述 | -|----------|-------------| -- |---------------| -| `sourceId` | `targetKey` | - | 移动的元素ID | -| `targetId` | `targetKey` | - | 与移动元素交换位置的元素ID | -| `sortField` | `string` | `sort` | 排序存储的字段名 | -| `targetScope` | `string` | - | 排序的scope，一个 resource 可以按照不同的 scope 排序 | -| `sticky` | `boolean` | - | 是否置顶移动的元素 | -| `method` | `insertAfter` \| `prepend` | - | 插入类型，插入目标元素之前还是之后 | +**Parameter** -## 关系资源资源操作 +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `sourceId` | `targetKey` | - | ID of the element to move | +| `targetId` | `targetKey` | - | ID of the element to switch position with the moving element | +| `sortField` | `string` | `sort` | The stored field names of sorting | +| `targetScope` | `string` | - | The scope of sorting, a resource can be sorted by different scopes | +| `sticky` | `boolean` | - | Whether or not to top the moving element | +| `method` | `insertAfter` \| `prepend` | - | Type of insertion, before or after the target element | + +## Resource Actions of Association Resource ### `add()` -添加与对象的关联关系，对应的 URL 为 `POST /api/:add`。适用于 `hasMany` 和 `belongsToMany` 关联。 +Add an association to an object. The corresponding URL is `POST /api/:add`. Apply to `hasMany` and `belongsToMany` associations. -**参数** +**Parameter** -| 参数名 | 类型 | 默认值 | 描述 | -|----------|-------------| --- | --- | -| `values` | `TargetKey \| TargetKey[]` | - | 添加的关联对象ID | +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `values` | `TargetKey \| TargetKey[]` | - | ID of the association object to add | ### `remove()` -移除与对象的关联关系，对应的 URL 为 `POST /api/:remove`。 -**参数** +Remove the association to an object. The corresponding URL is `POST /api/:remove`. -| 参数名 | 类型 | 默认值 | 描述 | -|----------|-------------| --- | --- | -| `values` | `TargetKey \| TargetKey[]` | - | 移除的关联对象ID | +**Parameter** + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `values` | `TargetKey \| TargetKey[]` | - | ID of the associated object to remove | ### `set()` -设置关联的关联对象，对应的 URL 为 `POST /api/:set`。 -**参数** +Set the associated association object. The corresponding URL is `POST /api/:set`. -| 参数名 | 类型 | 默认值 | 描述 | -|----------|-------------| --- | --- | -| `values` | `TargetKey \| TargetKey[]` | - | 设置的关联对象的ID | +**Parameter** + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `values` | `TargetKey \| TargetKey[]` | - | ID of the association object to set | ### `toggle()` -切换关联的关联对象，对应的 URL 为 `POST /api/:toggle`。`toggle` 在内部判断关联对象是否已经存在，如果存在则移除，如果不存在则添加。 +Toggle the associated association object. The corresponding URL is `POST /api/:toggle`. `toggle` internally determines if the associated object already exists, removes it if it does, otherwise adds it. -**参数** +**Parameter** -| 参数名 | 类型 | 默认值 | 描述 | -|----------|-------------| -- | --- | -| `values` | `TargetKey` | - | 切换的关联对象的ID | +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `values` | `TargetKey` | - | ID of the association object to toggle |