根据 Microsoft Word 模板导出规范（11 月更新）

利用 Requirements & Systems Portal 的 Python 和 Rest API（允许完全访问所有数据），并结合 Microsoft Word 的合并字段功能，可以一键将需求规格导出为 Word 文档。通过该功能，您可以选择在文档中包含哪些需求字段以及如何放置这些字段。

合并字段和模板

合并字段通过其名称作为数据字段的参考。当模板文档与数据源中的值进行邮件合并时，数据字段信息将取代合并字段。

通过创建具有不同合并字段的模板文档，可以根据它们快速生成相同类型的输出文档（规格或其他）。

创建新的合并字段

1. 打开要编辑的文档，转到 Insert选项卡。

2. 打开 Quick Partd菜单，然后选择 Field.对话框窗口将打开。 Field对话窗口将打开。

3. 在字段对话框菜单中选择 Merge Field。在右侧的 Field name文本框中输入合并字段名称，然后单击 OK.
   提示：根据要替换的数据命名字段，以便于跟踪

4. 合并字段将插入 Word 文件。单击该对象后，它将以灰色高亮显示。

已经定义了相应 Python 函数的合并字段有

"req_id" - 需求标识符
"req_title" - 需求标题
"req_text" - 需求文本
"req_state" - 需求状态 
"req_type" - 需求类型
"req_rationale" - 与需求相关的理由 
"images" - 附加到需求的图像
"specification_name" - 包含该要求的规范
"section_name" - 包含该要求的章节
"req_compliance" - 符合要求的声明
"req_comp_comment" - 符合要求的注释
"req_owner" - 要求的所有者 
"req_applicability" - 要求的适用性
"要求 "验证方法
req_ver_m_text" - 要求 "验证方法注释
req_ver_closeout_ref" - "需求 "验证方法关闭引用
"req_ver_status" - 需求'验证方法状态

创建模板（用于模板复制）

合并字段的组合可用于创建用于生成规范文档的模板文件。

下图是一个模板示例，其中一些字段写在 "纯文本 "上，另一些则作为表格的一部分。该示例是下一节将介绍的 Python 脚本的基础示例。

该模板的输出结果与下图类似

填充模板的 Python 脚本

Python 脚本用于根据合并字段填充的模板生成文档，主要使用以下软件包：

• valispace - Requirements & Systems Portal 的 python API 可让您访问和更新 Requirements & Systems Portal 中的对象。

• docx-mailmerge2 - 在 Office Open XML (Docx) 文件上执行邮件合并（用所需数据替换合并字段），无需安装 Microsoft Office Word 即可在任何系统上使用。

• python-docx - 用于创建和更新 Microsoft Word (.docx) 文件的 Python 库。

• htmldocx - 将 HTML 转换为 Docx 的 Python 库。用于保持从 Requirements & Systems Portal 到 Word 的格式（粗体、斜体、项目符号......）。

代码分为 3 类函数：

• Master functions - 由 main和 create_specification_document函数，其逻辑是通过填充给定模板，将需求导出为最终文档

• Requirement data extract functions- 提取需求数据（如需求类型、状态、图像等）的所有函数

• Document "Format" functions- 执行格式化的函数，如去除空白、确保表格不会在最终生成的文档中断开

在下面的章节中，我们将简要介绍这些功能。

主函数 - 主

该函数允许用户插入域名、用户名和密码、项目标识符（生成规范的依据）以及模板文件的路径。

然后，它将使用这些信息来

1. 使用 Python API 登录需求与系统门户；

2. 下载项目通用数据，如规格、图像、需求类型等；

3. 调用函数 create_specification_document为所选项目中的每个规范调用函数。

主函数 - 创建规格文件

该函数将通过在模板上的合并字段中填入相应的需求数据来创建生成规格文件。

最初，需要收集所选规范的所有需求：

all_specification_requirements = get_map(api, f "requirements/complete/?project="+str(DEFAULT_VALUES["project"])+"&clean_html=text&clean_text=comment", "id", None, filter_specification)
    如果 len(all_specification_requirements) 1：
        print("No requirements for Specification -> "+ specification_data['name'])
        返回

然后，它将按章节组织需求数据，从没有任何章节的需求开始。

为了获取这些非章节需求，支持函数 get_requirements_without_section用于过滤所有没有组的规格要求（在 Requirements & Systems Portal 的后台，各部分是如何存储的），并按字母顺序排序。

    #首先，我们将在文档中添加无章节需求
    no_section_requirements = get_requirements_without_section(all_specification_requirements)

现在，所有非章节需求都已收集完毕，是时候准备数据来填充合并字段了。这些数据将借助 Requirement data extract functions的帮助下获取数据，并存储在 python 列表中，如下代码所示。

template_data.append({
                "specification_name" : CURRENT_SPECIFICATION["name"] if counter == 1 else ""、
                "section_name" : ""、 
                "req_id" : reqdata['标识符']、
                "req_title"：reqdata['title']、
                "req_text"：reqdata['标识符']+"_docx"、
                "req_type" : req_type、
                "req_rationale"：reqdata['comment']、
                "req_ver_methods" : req_vms、
                "req_applicability"： req_applicability、 
                "images" : "Images_Placeholder_"+str(requirement) if requirement_with_images == True else "No_Images" (无图像)
            })

对于大多数合并字段，数据是直接映射的，但对于 images和req_text的数据将在稍后阶段合并：

• 对于 images标记，表明需求是否有图像，是否存储为数据

• 对于 req_text占位符会作为数据存储。该占位符还将用作列表中的键，该列表包含将需求文本从 HTML 解析为 Word 的结果，如下代码所示

  docx_list[reqdata['identifier']+"_docx"] = new_parser.parse_html_string(reqdata['text'])

对于有章节的需求，将重复同样的过程，一旦完成，数据将合并到模板字段中，并存储为一个新文件：

document.merge_templates(template_data, separator='continuous_section')
document.write(OUTPUT_FILE)

最后，我们将使用 Document "Format" functions删除空章节和空标题，将表格保留在一页上，将格式化的需求文本及其图片插入文档，从而最终完成文档

    document2 = Document(OUTPUT_FILE)
    remove_all_but_last_section(document2)
    remove_all_empty_headings(document2)
    put_html_text(document2, docx_list)
    put_images(document2, all_project_images)   
    keep_tables_on_one_page(document2)

    document2.save(OUTPUT_FILE)
    print ("Specification document created -> "+ specification_data['name'])

需求数据提取函数

从需求中提取数据的函数如下：

• get_requirements_without_section - 返回不含章节的所有需求的排序列表

• get_specification_sections - 返回给定规范的所有章节列表

• get_section_requirements - 返回给定部分所有需求的排序列表

• get_requirement_images - 返回所有需求图像的数组

• get_requirement_type - 返回需求类型的名称

• get_requirement_state - 返回需求名称 状态

• get_requirement_owner - 返回用户组和需求所有者的名字和姓氏

• get_requirement_applicability - 返回所有适用需求块类型的列表，以"; "分隔

• get_requirement_verification_methods - 返回所有需求验证方法的名称，以"; "分隔

• get_requirement_verification_methods_newline - 返回所有需求验证方法的名称，以换行符分隔

• get_requirement_verification_methods_comments - 返回所有需求验证方法的注释，用双换行符分隔

• get_requirement_verification_status - 返回所有需求验证方法的状态，以"; "分隔

• get_requirement_verification_closeout_refs - 返回每个需求验证方法的关闭引用名称，以"; "分隔

• get_requirement_attachments_references - 返回所有需求附件的名称，用"; "分隔

• get_requirement_custom_field - 返回作为参数传递给函数的需求上特定自定义字段的值

文档 "格式 "函数

用于格式化最终文档的函数如下：

• keep_tables_on_one_page - 格式化最终文档，使表格的单元格内容不能跨越不同页面。

• remove_all_empty_headings - 格式化最终文档，删除所有空标题

• remove_all_but_last_section - 格式化最终文档，使其只有一个部分，而不是多个部分

• put_images - 用每个需求的图片替换图片占位符

• clone_run_props - 将运行的属性复制到另一个运行的辅助函数（用于复制 HTML 格式的文本属性）

• put_html_text - 将需求文本占位符替换为相应的格式化文本，如粗体、斜体、下划线、删除线和圆点。

下载最新的通用模板、Python 脚本或可执行文件

通用规范创建 Nov2023.py 通用规范模板.docx 要求.txt

运行脚本前需要编辑的内容：

从创建脚本到生成文档，运行此代码的完整过程已在下面的视频中说明（无音频）。

Line 27 - Line 30用户需要为脚本的运行定义用户名和密码。用户可以使用秘密管理并运行脚本，也可以在脚本中直接输入用户名和密码。但是，部署中的所有用户都可以看到密码。因此，我们建议您使用 "秘密管理"。

Line 31 复制规范名称并在此行中输入。

Line 32将通用规范模板上传到文件管理，复制其 "ID "并添加到这一行。

Line 33 添加规范所在项目的 "ID"。

Line 34您可以为导出的文件提供一个名称。

如果您需要有关更改模板、提取其他信息以填充模板的指导，或与此功能相关的任何问题，请随时通过我们的Altium 支持页面向我们发送您的问题/请求。