PageForm 页面表单模块

PageForm 模块是 DarkM 框架的页面和表单管理模块，提供了页面配置、文章管理、海报管理、启动动画等功能。支持页面可视化配置、文章发布管理、海报生成等功能，满足企业移动端页面运营需求。

---

📋 模块概述

属性	说明
模块名称	PageForm（页面表单）
模块类型	业务模块
依赖关系	依赖 Admin 模块、Common 模块、Record 模块
必需性	可选（移动端运营必需）
Git 仓库	framework/darkm/darkm (opens new window)

---

🎯 核心功能

功能清单

功能分类	功能	说明	重要性
页面配置	页面配置	页面头部配置	⭐⭐⭐⭐⭐
	页面配置详情	页面详情配置	⭐⭐⭐⭐⭐
	页面配置头部	页面头部管理	⭐⭐⭐⭐
文章管理	文章管理	文章内容管理	⭐⭐⭐⭐⭐
	文章目录	文章分类目录	⭐⭐⭐⭐
	文章访问统计	文章访问统计	⭐⭐⭐⭐
海报管理	海报管理	海报图片管理	⭐⭐⭐⭐
	海报图片	海报图片上传	⭐⭐⭐⭐
	我的海报	个人海报管理	⭐⭐⭐
启动动画	启动动画头部	启动动画头部	⭐⭐⭐
	启动动画详情	启动动画详情	⭐⭐⭐

---

📦 安装配置

NuGet 包安装

Install-Package DarkM.Module.PageForm.Web -Version 1.0.0

NPM 包安装

npm i -S darkm-module-pageform

配置文件

{
  "Db": {
    "Modules": [
      {
        "Name": "PageForm",
        "Database": "Nm_PageForm",
        "Prefix": ""
      }
    ]
  },
  "PageForm": {
    // 是否开启页面表单服务
    "Enable": true,
    // 图片上传路径
    "UploadPath": "/upload/pageform",
    // 单张图片大小限制（MB）
    "MaxImageSize": 5
  }
}

配置说明：

配置项	说明	默认值
Enable	是否开启页面表单服务	true
UploadPath	图片上传路径	/upload/pageform
MaxImageSize	单张图片大小限制（MB）	5

---

🗄️ 数据库表结构

页面配置表

表名	说明	主键
PageConfig	页面配置表	Id (Guid)
PageConfigHeader	页面配置头部表	Id (Guid)
PageConfigDetail	页面配置详情表	Id (long)

文章管理表

表名	说明	主键
Article	文章表	Id (long)
ArticleCatalog	文章目录表	Id (long)
ArticleVisitTotal	文章访问统计表	Id (long)

海报管理表

表名	说明	主键
Poster	海报表	Id (Guid)
PosterImage	海报图片表	Id (long)
MyPoster	我的海报表	Id (long)

启动动画表

表名	说明	主键
BootAnimationHeader	启动动画头部表	Id (Guid)
BootAnimationDetail	启动动画详情表	Id (long)

---

🔐 权限系统设计

Controller 定义

1. 页面配置管理

[Description("页面配置管理")]
public class PageConfigController : ModuleController
{
    private readonly IPageConfigService _service;

    public PageConfigController(IPageConfigService service)
    {
        _service = service;
    }

    [HttpGet]
    [Description("查询")]
    public Task<IResultModel> Query([FromQuery]PageConfigQueryModel model)
    {
        return _service.Query(model);
    }

    [HttpPost]
    [Description("添加")]
    public Task<IResultModel> Add(PageConfigAddModel model)
    {
        return _service.Add(model);
    }

    [HttpDelete]
    [Description("删除")]
    public Task<IResultModel> Delete([BindRequired]Guid id)
    {
        return _service.Delete(id);
    }

    [HttpGet]
    [Description("编辑")]
    public Task<IResultModel> Edit([BindRequired]Guid id)
    {
        return _service.Edit(id);
    }

    [HttpPost]
    [Description("修改")]
    public Task<IResultModel> Update(PageConfigUpdateModel model)
    {
        return _service.Update(model);
    }
}

2. 文章管理

[Description("文章管理")]
public class ArticleController : ModuleController
{
    private readonly IArticleService _service;

    public ArticleController(IArticleService service)
    {
        _service = service;
    }

    [HttpGet]
    [Description("查询")]
    public Task<IResultModel> Query([FromQuery]ArticleQueryModel model)
    {
        return _service.Query(model);
    }

    [HttpPost]
    [Description("添加")]
    public Task<IResultModel> Add(ArticleAddModel model)
    {
        return _service.Add(model);
    }

    [HttpDelete]
    [Description("删除")]
    public Task<IResultModel> Delete([BindRequired]long id)
    {
        return _service.Delete(id);
    }

    [HttpGet]
    [Description("编辑")]
    public Task<IResultModel> Edit([BindRequired]long id)
    {
        return _service.Edit(id);
    }

    [HttpPost]
    [Description("修改")]
    public Task<IResultModel> Update(ArticleUpdateModel model)
    {
        return _service.Update(model);
    }

    [HttpPost]
    [Description("发布")]
    public Task<IResultModel> Publish([BindRequired]long id)
    {
        return _service.Publish(id);
    }
}

权限解析结果

权限编码	说明	访问级别
pageform_pageconfig_query_get	页面配置 - 查询	需授权
pageform_pageconfig_add_post	页面配置 - 添加	需授权
pageform_pageconfig_edit_get	页面配置 - 编辑	需授权
pageform_pageconfig_update_post	页面配置 - 修改	需授权
pageform_pageconfig_delete_delete	页面配置 - 删除	需授权
pageform_article_query_get	文章管理 - 查询	需授权
pageform_article_add_post	文章管理 - 添加	需授权
pageform_article_update_post	文章管理 - 修改	需授权
pageform_article_publish_post	文章管理 - 发布	需授权
pageform_articlecatalog_query_get	文章目录 - 查询	需授权

---

🎨 核心功能详解

一、页面配置

1. 页面配置实体

[Table("PageConfig")]
public partial class PageConfigEntity : EntityBase
{
    /// <summary>
    /// 页面名称
    /// </summary>
    [Length(100)]
    public string PageName { get; set; }

    /// <summary>
    /// 页面编码
    /// </summary>
    [Length(50)]
    public string PageCode { get; set; }

    /// <summary>
    /// 页面类型
    /// </summary>
    public PageType PageType { get; set; }

    /// <summary>
    /// 页面状态
    /// </summary>
    public PageStatus Status { get; set; }

    /// <summary>
    /// 页面配置（JSON 格式）
    /// </summary>
    [Length(5000)]
    public string PageConfigJson { get; set; }
}

2. 页面类型枚举

public enum PageType
{
    /// <summary>
    /// 首页
    /// </summary>
    Home = 0,

    /// <summary>
    /// 活动页
    /// </summary>
    Activity = 1,

    /// <summary>
    /// 专题页
    /// </summary>
    Topic = 2,

    /// <summary>
    /// 自定义页
    /// </summary>
    Custom = 3
}

---

二、文章管理

1. 文章实体

[Table("Article")]
public partial class ArticleEntity : EntityBase
{
    /// <summary>
    /// 文章标题
    /// </summary>
    [Length(200)]
    public string Title { get; set; }

    /// <summary>
    /// 文章摘要
    /// </summary>
    [Length(500)]
    public string Summary { get; set; }

    /// <summary>
    /// 文章内容
    /// </summary>
    [Length(50000)]
    public string Content { get; set; }

    /// <summary>
    /// 封面图片
    /// </summary>
    [Length(500)]
    public string CoverImage { get; set; }

    /// <summary>
    /// 文章状态
    /// </summary>
    public ArticleStatus Status { get; set; }

    /// <summary>
    /// 发布时间
    /// </summary>
    public DateTime? PublishTime { get; set; }
}

2. 文章状态枚举

public enum ArticleStatus
{
    /// <summary>
    /// 草稿
    /// </summary>
    Draft = 0,

    /// <summary>
    /// 已发布
    /// </summary>
    Published = 1,

    /// <summary>
    /// 已下架
    /// </summary>
    Offline = 2
}

---

三、文章目录

1. 目录实体

[Table("ArticleCatalog")]
public partial class ArticleCatalogEntity : EntityBase
{
    /// <summary>
    /// 目录名称
    /// </summary>
    [Length(100)]
    public string CatalogName { get; set; }

    /// <summary>
    /// 父级 ID
    /// </summary>
    public long ParentId { get; set; }

    /// <summary>
    /// 层级
    /// </summary>
    public int Level { get; set; }

    /// <summary>
    /// 排序
    /// </summary>
    public int Sort { get; set; }

    /// <summary>
    /// 是否启用
    /// </summary>
    public bool IsEnabled { get; set; }
}

---

🔧 核心服务接口

IPageConfigService（页面配置服务）

public interface IPageConfigService
{
    /// <summary>
    /// 查询页面配置列表
    /// </summary>
    Task<IResultModel> Query(PageConfigQueryModel model);

    /// <summary>
    /// 添加页面配置
    /// </summary>
    Task<IResultModel> Add(PageConfigAddModel model);

    /// <summary>
    /// 删除页面配置
    /// </summary>
    Task<IResultModel> Delete(Guid id);

    /// <summary>
    /// 编辑页面配置
    /// </summary>
    Task<IResultModel> Edit(Guid id);

    /// <summary>
    /// 修改页面配置
    /// </summary>
    Task<IResultModel> Update(PageConfigUpdateModel model);

    /// <summary>
    /// 获取页面配置详情
    /// </summary>
    Task<IResultModel> GetDetail(Guid id);

    /// <summary>
    /// 发布页面
    /// </summary>
    Task<IResultModel> Publish(Guid id);
}

IArticleService（文章服务）

public interface IArticleService
{
    /// <summary>
    /// 查询文章列表
    /// </summary>
    Task<IResultModel> Query(ArticleQueryModel model);

    /// <summary>
    /// 添加文章
    /// </summary>
    Task<IResultModel> Add(ArticleAddModel model);

    /// <summary>
    /// 删除文章
    /// </summary>
    Task<IResultModel> Delete(long id);

    /// <summary>
    /// 编辑文章
    /// </summary>
    Task<IResultModel> Edit(long id);

    /// <summary>
    /// 修改文章
    /// </summary>
    Task<IResultModel> Update(ArticleUpdateModel model);

    /// <summary>
    /// 发布文章
    /// </summary>
    Task<IResultModel> Publish(long id);

    /// <summary>
    /// 下架文章
    /// </summary>
    Task<IResultModel> Offline(long id);

    /// <summary>
    /// 获取文章详情
    /// </summary>
    Task<IResultModel> GetDetail(long id);
}

IArticleCatalogService（文章目录服务）

public interface IArticleCatalogService
{
    /// <summary>
    /// 查询文章目录列表
    /// </summary>
    Task<IResultModel> Query(ArticleCatalogQueryModel model);

    /// <summary>
    /// 添加文章目录
    /// </summary>
    Task<IResultModel> Add(ArticleCatalogAddModel model);

    /// <summary>
    /// 删除文章目录
    /// </summary>
    Task<IResultModel> Delete(long id);

    /// <summary>
    /// 编辑文章目录
    /// </summary>
    Task<IResultModel> Edit(long id);

    /// <summary>
    /// 修改文章目录
    /// </summary>
    Task<IResultModel> Update(ArticleCatalogUpdateModel model);

    /// <summary>
    /// 获取目录树
    /// </summary>
    Task<IResultModel> GetTree();
}

---

🖥️ 前端组件说明

NPM 包信息

{
  "name": "darkm-module-pageform",
  "version": "1.5.0-beta-2.0",
  "code": "pageForm",
  "title": "页面表单",
  "dependencies": {
    "darkm-module-admin": "^1.5.0-beta-2.0",
    "darkm-module-common": "^1.5.0-beta-2.0",
    "darkm-module-record": "^1.5.0-beta-2.0",
    "darkm-ui": "^1.5.0-beta-2.0"
  }
}

组件目录结构

src/UI/module-pageform/
├── src/
│   ├── views/                      # 页面组件
│   │   ├── pageConfig/             # 页面配置
│   │   ├── article/                # 文章管理
│   │   ├── articleCatalog/         # 文章目录
│   │   ├── poster/                 # 海报管理
│   │   └── bootAnimation/          # 启动动画
│   └── components/                 # 通用组件
│       ├── pageConfig-select/      # 页面配置选择器
│       ├── pageConfig-search-select/ # 页面配置搜索选择器
│       ├── article-select/         # 文章选择器
│       ├── article-search-select/  # 文章搜索选择器
│       ├── articleCatalog-select/  # 文章目录选择器
│       ├── articleCatalog-tree-select/ # 文章目录树选择器
│       ├── poster-select/          # 海报选择器
│       └── config-pageform/        # 页面表单配置组件
└── package.json

---

📦 通用组件详解

1. PageConfigSelect 页面配置选择器

组件路径： components/pageConfig-select

功能： 下拉选择页面配置

使用示例：

<template>
  <pageConfig-select v-model="pageId" />
</template>

<script>
import { components } from 'darkm-module-pageform'
const { PageConfigSelect } = components

export default {
  components: { PageConfigSelect },
  data() {
    return {
      pageId: ''
    }
  }
}
</script>

Props 参数：

参数	类型	必填	默认值	说明
value	String	否	-	选中的页面 ID（v-model）
disabled	Boolean	否	false	是否禁用

Events 事件：

事件名	参数	说明
input	(value: String)	选中值变化时触发（v-model）
change	(value: String, data: Object)	选中值变化时触发，返回完整数据

---

2. ArticleSelect 文章选择器

组件路径： components/article-select

功能： 下拉选择文章

使用示例：

<template>
  <article-select 
    v-model="articleId"
    :catalogId="catalogId"
  />
</template>

<script>
import { components } from 'darkm-module-pageform'
const { ArticleSelect } = components

export default {
  components: { ArticleSelect },
  data() {
    return {
      articleId: '',
      catalogId: 1
    }
  }
}
</script>

Props 参数：

参数	类型	必填	默认值	说明
value	Number	否	-	选中的文章 ID（v-model）
catalogId	Number	否	-	目录 ID 筛选
disabled	Boolean	否	false	是否禁用

Events 事件：

事件名	参数	说明
input	(value: Number)	选中值变化时触发（v-model）
change	(value: Number, data: Object)	选中值变化时触发，返回完整数据

---

3. ArticleCatalogTreeSelect 文章目录树选择器

组件路径： components/articleCatalog-tree-select

功能： 树形选择文章目录

使用示例：

<template>
  <articleCatalog-tree-select 
    v-model="catalogId"
    :collapseAll="false"
  />
</template>

<script>
import { components } from 'darkm-module-pageform'
const { ArticleCatalogTreeSelect } = components

export default {
  components: { ArticleCatalogTreeSelect },
  data() {
    return {
      catalogId: ''
    }
  }
}
</script>

Props 参数：

参数	类型	必填	默认值	说明
value	Number	否	-	选中的目录 ID（v-model）
collapseAll	Boolean	否	true	是否默认折叠所有节点
disabled	Boolean	否	false	是否禁用

Events 事件：

事件名	参数	说明
input	(value: Number)	选中值变化时触发（v-model）
change	(value: Number, data: Object)	选中值变化时触发，返回完整数据

特点：

• ✅ 树形结构展示
• ✅ 支持层级展开/折叠
• ✅ 基于 mixins.treeSelect

---

📋 组件使用注意事项

1. 组件引入方式

// 方式一：引入单个组件
import { components } from 'darkm-module-pageform'
const { PageConfigSelect, ArticleSelect } = components

// 方式二：全局注册
import PageForm from 'darkm-module-pageform'
Vue.use(PageForm)

2. v-model 双向绑定

所有选择器组件都支持 v-model 双向绑定：

<!-- 推荐用法 -->
<article-select v-model="articleId" />

<!-- 等价于 -->
<article-select 
  :value="articleId" 
  @input="articleId = $event" 
/>

3. 级联选择

多个选择器可以级联使用：

<template>
  <div>
    <articleCatalog-tree-select v-model="catalogId" />
    <article-select v-model="articleId" :catalogId="catalogId" />
  </div>
</template>

4. 数据格式

所有组件返回的数据格式：

• 单选： 返回 ID（String/Number）
• change 事件： 返回 (value, data)，data 为完整对象

5. 组件依赖

PageForm 模块依赖以下模块：

• darkm-module-admin - 权限管理
• darkm-module-common - 通用模块
• darkm-module-record - 访问记录
• darkm-ui - UI 组件库

确保先安装依赖：

npm install darkm-module-admin --registry http://npm.woowis.com
npm install darkm-module-common --registry http://npm.woowis.com
npm install darkm-module-record --registry http://npm.woowis.com
npm install darkm-ui --registry http://npm.woowis.com

---

🔍 常见问题

1. 图片上传失败

问题： 上传海报图片报错

解决：

# 检查上传目录是否有写权限
ls -la /upload/pageform

# 检查图片大小是否超过限制
# 检查图片格式是否支持（JPG/PNG/GIF）

# 查看详细错误日志
tail -f logs/pageform.log

2. 文章发布失败

问题： 点击发布按钮报错

解决：

1. 检查文章必填字段是否完整
2. 检查文章目录是否选择
3. 检查封面图片是否上传
4. 查看后端日志错误信息

3. 页面配置无法保存

问题： 保存页面配置时报错

解决：

1. 检查页面配置 JSON 格式是否正确
2. 检查必填字段是否完整
3. 检查页面编码是否重复
4. 查看数据库连接是否正常

4. 文章目录树无法加载

问题： 目录树加载失败

解决：

# 检查目录数据是否正常
# 检查目录层级关系是否正确（避免循环引用）
# 查看前端控制台错误信息

---

📚 相关文档

• Admin 权限管理 - 权限配置
• Record 访问记录 - 访问统计
• Common 通用模块 - 通用功能
• 系统架构 - 整体架构

---

🔗 参考链接

• 页面配置最佳实践 (opens new window)
• 富文本编辑器 (opens new window)
• 图片上传优化 (opens new window)
• GitLab 仓库 (opens new window)

---

最后更新: 2026-03-20