在安企CMS（AnQiCMS）中，内容运营者常常需要灵活地展示网站上的重要内容，例如将特定文章设置为“头条”或“幻灯”来吸引用户的注意力。安企CMS为此提供了一个非常实用的功能，那就是通过“推荐属性”（flag）来标记文档。如果您想获取这些被特殊标记的文档列表，AnQiCMS的API接口能够帮助您轻松实现。

理解文档的“推荐属性”（flag）

在安企CMS中，每一篇文档都可能拥有一个或多个推荐属性，这些属性用单个字母进行标记，方便网站进行分类和展示。例如：

  • 头条：用 h 标记，通常用于网站首页最醒目的位置，展示最重要的内容。
  • 幻灯：用 f 标记，常用于轮播图或幻灯片展示区，以图片配合标题的形式吸引用户。
  • 其他常见的属性还包括：推荐 c、特荐 a、滚动 s、加粗 h（注意，这里 h 既可表示头条也可表示加粗，但通常在内容管理中会约定用途）、图片 p、跳转 j 等。

一篇文档可以同时拥有多个属性，比如既是“头条”又是“幻灯”，那么它的 flag 值可能就是 hf。了解这些标记是获取特定文档列表的基础。

使用 archive/list 接口获取文档列表

要获取带有特定推荐属性的文档列表，我们需要利用安企CMS提供的 archive/list 接口。这是一个非常强大的接口，允许您根据多种条件筛选文档。

接口基础信息

  • API 调用地址：{域名地址}/api/archive/list
  • 调用方法：GET

核心参数：flag

在 archive/list 接口的众多请求参数中，flag 参数就是我们实现目标的关键。它允许您指定需要匹配的推荐属性。

如何使用 flag 参数：

  1. 获取具有单一推荐属性的文档：如果您想获取所有被标记为“头条”的文档，只需将 flag 参数设置为 h，即 flag="h"。同样地，获取“幻灯”文档就是 flag="f"。
  2. 获取具有多个推荐属性之一的文档：如果您希望获取那些要么是“头条”，要么是“幻灯”的文档，可以将多个 flag 值用逗号 , 分隔。例如，要获取“头条”或“幻灯”的文档，参数设置为 flag="h,f"。此时，只要文档的 flag 属性中包含 h 或 f 任意一个，都会被检索出来。

结合其他实用参数

除了 flag 之外，您通常还会配合其他参数来精确控制返回结果：

  • moduleId：强烈建议指定文档所属的模型ID，例如文章模型ID通常是 1。这样可以避免获取到其他模型（如产品模型）的文档，确保数据的一致性。例如，moduleId=1。
  • limit：控制返回的文档数量。如果您只需要展示几篇，可以设置 limit=5。如果需要分页，也可以使用 limit="2,10" 来指定从第2条开始获取10条数据。
  • type：当您需要获取总数并进行分页展示时，可以设置 type="page"。如果只是简单获取一个列表，默认的 list 类型即可。
  • order：您可以根据需要设置排序方式，例如 order="created_time desc" 表示按发布时间倒序排列，order="views desc" 则表示按浏览量倒序排列。

实际操作示例

为了更好地理解，我们来看看几个具体的API请求示例。假设您的网站域名是 www.yourdomain.com，文章模型ID是 1。

1. 获取所有标记为“头条”的最新文章，最多5篇：

{域名地址}/api/archive/list?moduleId=1&flag=h&limit=5&order=created_time desc

替换 {域名地址} 为 https://www.yourdomain.com，完整的请求看起来会是： https://www.yourdomain.com/api/archive/list?moduleId=1&flag=h&limit=5&order=created_time desc

2. 获取所有标记为“幻灯”的热门文章，不限制数量，并支持分页：

{域名地址}/api/archive/list?moduleId=1&flag=f&type=page&order=views desc&page=1&limit=10

这将获取文章模型下，所有flag中包含f属性的文档，按浏览量倒序排列，每页10条，获取第一页。

3. 获取所有标记为“头条”或“幻灯”的文档，随机显示3篇：

{域名地址}/api/archive/list?moduleId=1&flag=h,f&limit=3&order=rand()

（请注意，rand() 并非所有数据库或API都支持，这里仅作示意，实际可能需要后台支持或前端随机选择）

解读返回数据

当您发起请求后，接口会返回一个JSON格式的数据。成功的响应会包含 code: 0 和一个 data 数组，其中每个元素都是一个文档对象。您可以在每个文档对象中找到 title、description、thumb（缩略图）、link（文档链接）以及我们关注的 flag 字段等信息。通过这些数据，您可以将精选的文档内容呈现在您的网站上。

通过以上步骤，您就可以在AnQiCMS中精准地获取到具有特定推荐属性的文档列表，为您的网站内容运营提供强大支持。

常见问题 (FAQ)

Q1: 如果我想获取同时具有“头条”和“幻灯”这两个属性的文档，API请求应该如何设置？ A1: 安企CMS的 flag 参数设计为通过逗号分隔来匹配“或”关系（即包含任一指定属性）。如果一个文档同时具有 h 和 f 属性（例如其 flag 字段值为 hf），那么您通过 flag="h" 或 flag="f"，甚至 flag="h,f" 都能获取到它。API层面没有直接的“与”逻辑筛选方式，但通常一个文档若被标记为“头条”且“幻灯”，其 flag 字段本身会同时包含 h 和 f，flag="h,f" 就可以满足大部分“或”关系的需求。

Q2: moduleId 参数为什么如此重要，如果我不指定会怎样？ A2: moduleId 用于指定文档所属的模型，例如文章、产品、图片等。每个模型下的文档结构可能不同，内容也千差万别。如果不指定 moduleId，接口可能会在所有模型中搜索，导致返回不相关的数据，或者返回的数据结构不符合您的预期，从而影响前端展示的准确性。明确指定 moduleId 可以确保您获取到的是目标模型下的内容，提高数据准确性和接口效率。

Q3: 获取到文档列表后，如何将这些内容展示到我的网站页面上？ A3: 获取到文档列表的JSON数据后，您需要根据您的前端技术栈（如HTML、CSS、JavaScript，或Vue/React等框架）来解析这些数据。通常会遍历 data 数组，为每个文档动态生成HTML元素，展示其标题、缩略图、简介，并链接到文档详情页。您可以利用返回数据中的 title、thumb、description 和 link 字段进行排版和渲染，从而在网站上形成一个精美的“头条”或“幻灯”区域。