定义自定义文档接口以导入需求

您可以定义自定义文档接口来导入Requirements Toolbox™未提供内置支持的第三方应用程序的需求。要定义自定义文档接口，请创建一个函数，指定导入过程中要使用的接口属性和回调函数。您还可以为受支持的产品创建内置 Requirements Toolbox 文档界面的自定义版本，例如 Microsoft^® Word。内置文档界面的自定义版本可以具有与内置类型不同的属性或回调函数。

或者，您可以通过导入 ReqIF™ 文件来导入 Requirements Toolbox 不支持的第三方应用程序的需求。有关更多信息，请参阅从 ReqIF 文件导入需求。

注意

您还可以定义自定义文档接口，直接链接到Requirements Toolbox不支持的第三方应用程序的需求。有关更多信息，请参阅定义自定义文档界面以直接链接到需求。

定义自定义文档界面

定义用于导入需求的自定义文档接口：

编写一个函数，定义并返回文档接口对象 ReqMgr.LinkType 的实例。您的函数必须采用以下形式：
```
function docDomain = myDomainType
    docDomain = ReqMgr.LinkType;
end
```
docDomain变量代表文档接口对象。

为文档界面对象定义这些属性：

名称	描述	值类型	示例值
`Registration`	需求文档接口名称，指定为字符串标量或字符向量。该属性的值必须与文档接口定义函数名相同。	字符串字符向量	`custom_word`
`Label`	导入需求对话框中自定义文档类型的标签，指定为字符串标量或字符向量。	字符串字符向量	`"My Custom Document Interface"`
`IsFile`	基于文件的需求文档的指示器，指定为 `logical` `1` (true) 或 `0` (false)。如果您的需求文档是基于文件的，则将值设置为 `1`；如果您的需求文档不是基于文件的，则将值设置为 `0`。	`Logical` `1` (true) or `0` (false)	`1`
`Extensions`	允许基于文件的需求文档的文件类型扩展名，指定为字符向量单元元胞数组。对于非基于文件的需求文档，请留空。	字符向量元胞数组	`{'.doc','.docx'}`
`LocDelimeters`	用于指定需求文档中支持的位置标识符类型的字符，指定为字符串标量或字符数组，是以下一个或多个字符的组合： `?`:用于在文档中搜索文本 `@`:用作命名项，例如需求 ID `#`:页码或项目编号 `>`:项编号 `$`:电子表格中的单元格地址此属性是可选的。	包含以下一个或多个字符的字符数组：`?`、`@`、`#`、`>`、`$`	`'?@#'`

确定您的文档界面对象需要哪些回调函数：

回调	描述	必需还是可选？	函数语法和说明
`NavigateFcn`	使用需求编辑器中的在文档中显示从导入的需求导航到外部文档中的原始需求的函数	可选，但如果不定义此函数，在文档中显示按钮不起作用	`NavigateFcn(document,id)` 打开 `document` 指定的外部需求文档，以满足 `id` 指定的需求。
`ContentsFcn`	获取外部需求文档或服务器目录的函数	必需	`[labels,depths,ids] = ContentsFcn(document)` 以元胞数组的形式返回 `document` 指定的外部文档的需求信息。`labels` 包含需求文本，`ids` 包含需求标识符，`depths` 包含层次结构中需求的级别。
`BrowseFcn`	对于非基于文件的需求文档，点击“导入需求”对话框中的浏览按钮时要执行的函数。基于文件的需求域不需要此函数。	可选	`BrowseFcn` 在非基于文件的需求应用程序中打开需求文档的浏览器。
`SummaryFcn`	获取导入需求的 `Summary`属性的文本的函数	可选，但如果您不定义此函数，则必须手动将导入的属性映射到 `Summary`属性。有关更多信息，请参阅创建和编辑属性映射。	`summary = SummaryFcn(document,id)` 返回 `document` 指定的外部需求文档中标识符 `id` 指定的需求摘要。
`HtmlViewFcn`	函数用于获取富文本导入的需求内容的 HTML 视图，并将其分配给导入需求的 `Description`属性	可选，但如果您未定义该函数或 `TextViewFcn`，则必须手动将导入的属性映射到 `Description`属性。有关更多信息，请参阅创建和编辑属性映射。	`html = HtmlViewFcn(document,id)` 返回 `document` 指定的外部需求文档中标识符 `id` 指定的需求的 HTML 内容。
`TextViewFcn`	获取纯文本导入需求内容的纯文本视图的函数	可选，但如果您未定义该函数或 `HtmlViewFcn`，则必须手动将导入的属性映射到 `Description`属性。有关更多信息，请参阅创建和编辑属性映射。	`text = TextViewFcn(document,id)` 返回 `document` 指定的外部需求文档中标识符 `id` 指定的需求的纯文本内容。
`AttributeNamesFcn`	获取要导入的需求属性名称的函数	可选，但如果您不定义此函数，则您导入的需求没有自定义属性或属性，除了由 `SummaryFcn`、`HtmlViewFcn` 或 `TextViewFcn` 导入的属性或特性之外。有关自定义属性的更多信息，请参阅创建和编辑属性映射。	`[attributes,datatype] = AttributeNamesFcn(document,id)` 返回 `document` 指定的外部需求文档中标识符 `id` 指定的需求的属性名称 `attributes` 以及有关属性数据类型 `datatype` 的详细信息。如果属性类型是布尔值，则 `datatype` 输出是默认布尔值， `true` 或 `false`。如果属性类型是数字，则`datatype`输出是默认数字值。如果属性是枚举，则 `datatype` 输出是可能的枚举值的字符向量元胞数组。
`GetAttributeFcn`	获取要导入的需求属性值的函数	如果为 `AttributeNamesFcn` 定义回调函数则必填	`value = GetAttributeFcn(document,id,attrName)` 返回 `document` 指定的外部需求文档中标识符 `id` 指定的需求的属性 `attrName` 的属性值。
`CreateURLFcn`	获取超链接以导航至需求报告中的链接需求的函数	可选	`url = CreateURLFcn(document,documentURL,id)` 返回 `document` 指定的外部需求文档中标识符 `id` 指定的需求的 URL，或者文档 URL `documentURL`。
`UrlLabelFcn`	获取需求报告中需求导航 URL 的超链接文本的函数	如果为 `CreateURLFcn` 定义回调，则必填	`label = UrlLabelFcn(document,id)` 返回 `document` 指定的外部需求文档中标识符 `id` 指定的需求的标签。
`BacklinkCheckFcn`	检查外部需求文档中是否存在反向链接的函数。有关反向链接的更多信息，请参阅管理外部需求文档中的导航反向链接。	可选	`[linkExists,newLinkURL] = BacklinkCheckFcn(mwArtifactName,mwItemId,extDoc,extReq)` 检查外部需求文档 `extDoc` 中的外部需求 `extReq` 是否有指向工件`mwArtifactName` 中 `mwItemId` 指定的 MATLAB^® 或 Simulink^® 中的可链接项的反向链接。如果反向链接存在，`linkExists` 将返回 `true`，而 `newLinkURL` 将返回空。如果反向链接不存在，`linkExists` 将返回 `false`，而 `newLinkURL` 将包含要作为反向链接插入的 URL。
`BacklinkInsertFcn`	在外部需求文档中插入反向链接的函数。有关反向链接的更多信息，请参阅管理外部需求文档中的导航反向链接。	如果为 `BacklinkCheckFcn` 定义回调函数则必填	`[navCmd,dispText] = BacklinkInsertFcn(extDoc,extReq,mwSourceArtifact,mwItemId,mwDomain)` 使用工件文档接口 `mwDomain` 插入从外部需求文档 `extDoc` 中 `extReq` 指定的外部需求到 `mwSourceArtifact` 指定的工件中 `mwItemId` 指定的 MATLAB 或 Simulink 中的可链接项的反向链接。该函数返回反向链接使用的导航命令 `navCmd` 以及反向链接显示的超链接文本 `dispText`。
`BacklinksCleanupFcn`	检查外部需求文档中过时的反向链接的函数。有关反向链接的更多信息，请参阅管理外部需求文档中的导航反向链接。	可选，但如果未定义此函数，需求编辑器中的更新反向链接上下文菜单选项将无法检查和删除过时的反向链接	`[countRemoved, countChecked] = BacklinksCleanupFcn(extDoc,mwSourceArtifact,mwLinksDataMap)` 检查外部需求文档 `extDoc` 中指向 MATLAB 或 Simulink工件`mwSourceArtifact` 中的可链接项的反向反向链接，并删除 `mwLinksDataMap` 指定的 Requirements Toolbox 链接映射中没有对应前向链接的反向链接链接。 `[countRemoved, countChecked] = BacklinksCleanupFcn(extDoc,mwSourceArtifact,mwLinksDataMap,saveBeforeCleanup)` 在删除反向链接之前保存需求文档。
`BacklinkDeleteFcn`	删除外部需求文档中的反向链接的函数。有关反向链接的更多信息，请参阅管理外部需求文档中的导航反向链接。	可选	`success = BacklinkDeleteFcn(extDoc,extReq,mwSourceArtifact,mwItemId)` 从外部需求文档 `extDoc` 中删除 `extReq` 指定的外部需求的反向链接，该反向链接指向 `mwSourceArtifact` 指定的工件中 `mwItemId` 指定的 MATLAB 或 Simulink 中的可链接项。

将文档界面所需的回调函数编写为主函数中的本地函数。
将回调函数句柄分配给文档界面对象相应的属性。

有关自定义文档接口的示例，请参阅 custom_jira 函数。

open(fullfile(matlabroot,"toolbox","slrequirements","slrequirements","linktype_examples","custom_jira.m"))

定义内置文档界面的自定义版本

要定义内置文档界面的自定义版本：

编写一个函数，定义并返回其中一个内置文档接口的实例：
- Microsoft Word：linktypes.linktype_rmi_word
- Microsoft Excel^®: linktypes.linktype_rmi_excel
- IBM^® DOORS^®: linktypes.linktype_rmi_doors
您的函数必须采用以下形式：
```
function docDomain = custom_word
    docDomain = linktypes.linktype_rmi_word;
end
```
通过将文档界面对象的 Registration 和 Label属性设置为自定义值来覆盖它们。您还可以覆盖其他属性。有关更多信息，请参阅定义自定义文档界面。
确定要覆盖哪些回调函数。有关更多信息，请参阅定义自定义文档界面。
在主函数中将新的回调函数创作为本地函数。

将回调函数句柄分配给文档界面对象相应的属性。

例如，此代码将文档界面对象的 NavigateFcn属性设置为名为 myNavigateFcn 的本地函数。

function docDomain = custom_word
    docDomain = linktypes.linktype_rmi_word;
    docDomain.NavigateFcn = @myNavigateFcn;
end

function myNavigateFcn(document,id)

end

有关内置文档界面的自定义版本的示例，请参阅 custom_word 函数。

open(fullfile(matlabroot,"toolbox","slrequirements","slrequirements","linktype_examples","custom_word.m"))

导入时使用自定义文档界面

要在导入期间使用自定义文档接口：

注册自定义文档接口。
```
rmi register myDomainType
```
打开需求编辑器。有关更多信息，请参阅打开需求编辑器 App。
点击导入。
在导入需求对话框中，将文档类型设置为自定义文档接口。

有关导入需求的更多信息，请参阅从第三方应用程序导入需求。

自定义域接口注册在 MATLAB 会话之间持续存在。要注销文档接口，请输入：

rmi unregister myDomainType

另请参阅

App

需求编辑器