When you are using AnQiCMS to build a website and need to retrieve document content from the backend, you will often encounter the document list interface （/api/archive/list）。This interface provides a very importanttypeThe parameter determines how you will retrieve and process the document list data. Deep understandingtype="page"andtype="list"The core difference between these two modes is crucial for improving website performance, optimizing user experience, and developing features more flexibly.
type="list" mode: Efficiently retrieve small-scale data
type="list"The mode is the default behavior of the document list interface. Its design philosophy lies inQuickly and lightly obtain a fixed amount of document contentInstead of focusing on the overall scale of the data, when you only need to display a small selection of content in a specific block of the website, such as the 'Latest Releases' on the homepage, the 'Hot Recommendations' in the sidebar, or the 'Related Articles' on the article detail page, this pattern becomes very efficient.
In this mode, you can make use oflimitparameters to precisely control the number of documents returned, for examplelimit="5"It will return the latest 5 articles. It is worth mentioning that,limitIt also supports a "offset" usage, such aslimit="2,10"This means you want to skip the first two records and then retrieve the next 10 documents starting from the third. This mechanism is very flexible in certain specific display scenarios.
However,type="list"The characteristics of the pattern also determine its limitations: it will not include the total number of documents in the returned data (totalfield), and does not support keyword search (qParameters and advanced filtering features such as custom filtering. This makes it unsuitable for scenarios that require pagination display or complex search filtering.
type=“page” mode: A tool for building complete pagination and search functionality
withtype="list"different,type="page"Mode designed forScenarios requiring complete pagination, search, and advanced filtering functionalityIt is designed. If you are building a blog list page, news archive page, or product showcase center, users need to be able to browse all content, perform pagination operations, and even search for information through keywords or specific attributes, thentype="page"The pattern is your first choice.
When you are going totypeis set to"page"At that time, the interface will not only return the document list data of the current page, but also provide an additionaltotalField clearly indicates the total number of documents that meet the query conditions. ThistotalThe value is the key to building front-end pagination navigation, allowing users to intuitively understand the overall scale of the content and easily jump to different pages.
Furthermore,type="page"The mode unlocks multiple advanced features. You can配合pageparameters to specify which page of content to retrieve, andlimittogether with parameters define how many documents are displayed per page. More powerful is,qThe parameter can be used in this mode for keyword search, helping users quickly locate documents with specific keywords in the title; at the same time, if you have configured custom filter fields for the document model in the AnQiCMS backend, you can also pass URL query parameters in the form of (for examplegender=男To implement more detailed custom filtering.
Overview of core differences
In summary,type="page"andtype="list"The main differences are reflected in the following aspects:
- Data returned:
type="list"Only returns the specified number of documents, without the total count;type="page"Return the document list of the current page and providetotalthe total number of documents. - Pagination support:
type="list"not supportedpagePagination parameters；“type="page"SupportpageandlimitParameters to implement complete page turning function. - Advanced Query:
type="list"Does not support keyword search (q) and custom filtering;type="page"Fully supports these features, able to build more interactive list pages. - Applicable scenarios:
type="list"Suitable for quickly obtaining a small range of fixed quantities of display content, such as recommended positions;type="page"Suitable for pages that require a complete list of content, pagination browsing, search, and filtering.
In actual development, choose the appropriate one based on your content display requirementstypeA model that allows you to use AnQiCMS's data interface more efficiently, avoid unnecessary data transmission, and thus improve the loading speed and user experience of the website.
Frequently Asked Questions (FAQ)
Q1: Can I usetype="list"Do you want to use a pattern to get all the articles of the website?A1: It is not recommended to do this.type="list"The primary purpose of the pattern is to retrieve a small amount of data, it will not return the total number of articles, and fetching all articles at once may cause the request response to slow down due to the large amount of data, even resulting in timeouts. If you need to retrieve all articles and display them with pagination, you must usetype="page"Pattern.
Q2: intype="list"mode, limit="5,10"What does it mean?A2: limit="5,10"Indicate that you want to skip the first 5 records in the document list and start from the 6th record to get the next 10 document data.This is a "offset + quantity" retrieval method, which is very practical in certain specific local content display scenarios.
Q3: Why am I intype="list"mode and usingqparameters to search, but it did not work?A3: Keyword search (qParameters) and custom filtering features are designed fortype="page"patterns.type="list"The pattern focuses on simple, fixed-number content retrieval and therefore does not support these advanced query features. If you need to search or filter documents, be sure totypethe parameter topage.