In the AanQi CMS, the custom fields of documents are a manifestation of its strong flexibility. They allow us to add various unique attributes to content, thereby enabling more refined management and display of information.但对于许多开发者和运营人员来说，如何通过API准确地获取这些自定义字段的值，常常是一个需要明确的问题。extraField, you can easily handle these additional data.

Understandingextra字段：Custom Data Repository

When you make a request to the API of Anqi CMS for a single document detail or a document list, the returned data usually contains a field namedextrafield. ThisextraThe field, as the name implies, is a collection of 'additional' information, specifically used to store all the custom fields and their corresponding values that you configure for the document model in the background.It is an object type, whose internal structure is designed very intuitively, making it convenient for you to access programming.

To be specific,extraObject keys correspond to the "form field name" you set when creating custom fields in the Anqi CMS backend.field_name）。This key corresponds to a small object containing three properties:

  • name：This is the Chinese name of a custom field for easy understanding.
  • valueThis is the actual content filled in for this custom field, which is the data you hope to obtain.
  • defaultIf the user has not filled in this field, it will display the default value you set in the background.

How to get the value of a specific custom field? Take 'author' as an example

Assuming we want to retrieve the "authorauthorCustom fields.

To get detailed information about this document, we usually usearchive/detailthe interface. You can access the document through theIDor itsURL 别名（filename）to request this interface. For example, to request a document with an ID of 1:

GET {域名地址}/api/archive/detail?id=1

The data returned by the interface will be a JSON structure, which includesdataall detailed properties of the document. Withindatayou will findextrafields that may look like this:

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "欢迎使用AnqiCMS",
    // ... 其他常规字段 ...
    "extra": {
      "author": {
        "name": "作者",
        "value": "AnqiCMS",
        "default": ""
      },
      "certificate": {
        "name": "学历",
        "value": null,
        "default": null
      },
      "city": {
        "name": "城市",
        "value": "北京\n上海\n重庆\n广州\n天津",
        "default": "北京\n上海\n重庆\n广州\n天津"
      }
    },
    // ... 其他字段 ...
    "link": ""
  },
  "msg": ""
}

From the above example, we can clearly seeextraan object containsauthora key. To get the actual name of the author, you just need to follow the data pathdata.extra.author.valueEnglishresponse.data.extra.author.valueEnglishresponseEnglishresponse.data.extra.author.valueEnglish"AnqiCMS".

English

It is not only the details of a single document, but also when you accessarchive/lista series of document lists through the interface, each document item'sextraThe field will also include its custom field information.This means you can easily display custom information such as author, source, specific attributes, etc. directly in article lists, product display pages, and other places without having to make a separate request for each list item.

the way to getarchive/detailThe interface is completely the same. When traversing the document list, for each document object, you are still accessing it according to the 'form field call name' of the custom field.extrain the object.value.

Practical tips and注意事项

  1. The field name is crucialMake sure to remember the "Form Field Name" you defined in your backend custom field settingsfield_name）。This is the unique identifier for its value obtained through API programming. If forgotten, it can be obtained throughapi/module/detailto get the model details, which will list all custom fieldsfield_name.
  2. handle empty value situationsNot all documents will fill in all custom fields, or a field may not exist at all in some document models. Make sure in your code that you handle this situation properly.extraObject and its internal custom fields are checked for null values to avoid errors during program execution. For example, before trying to accessdata.extra.author.valuefirst, checkdata.extrawhether it exists, as well asdata.extra.authorwhether it exists.
  3. Distinguishnameandvalue:extraEach custom field object under the field hasnameandvaluetwo properties.namewhich is the display name of the field (e.g., “author”), whereasvalueis the actual content you need (e.g., “AnqiCMS”).

Through understanding and utilizingextraThe field, Anqi CMS provides you with an extremely convenient way to manage and display a rich variety of content attributes, making your website or app content more in-depth and flexible.

Common Questions (FAQ)

Q1: What if I don't know the 'Form Field Name' of the custom field?A1: You can confirm in two ways: first, log in to the Anqi CMS backend, go to “Content Management” -> “Model Management”, find the corresponding document model and click edit, where all the custom fields and their “form field names” under the model will be listed. Second, you can also callapi/module/detailInterface, pass in the model ID, in the returneddata.fieldsarray, find the custom field you want, itsfield_nameattribute is the corresponding call name.

Q2: Why do I getextraThe field is empty or does not contain the custom field I want?A2: This usually has several reasons:

1.  **文档未填写该字段**：如果该文档在编辑时，您在对应的自定义字段中留空了，那么 `extra` 中该字段的 `value` 就会是 `null`。
2.  **字段不属于该文档模型**：您可能试图获取的自定义字段并不属于当前文档所使用的模型。请检查后台模型配置。
3.  **接口类型**：只有 `archive/detail` 和 `archive/list` 这两个接口会在 `data` 中返回 `extra` 字段，其他接口如 `archive/prev` 或 `archive/next` 通常不包含此信息。

Q3:data.extra.your_field.nameanddata.extra.your_field.valueWhat is the difference? Which should I use?A3:data.extra.your_field.nameReturns the setting you have made for this custom field in the backgroundDisplay Name(for example, “Author”) anddata.extra.your_field.valueThe return is the actual content filled in for this field by the user when editing the documentwhile editing the documentFor example, “AnqiCMS”. In most cases, you would want to retrieve and display the content filled in by the user, so you should usedata.extra.your_field.value.