字段、链接和审阅 API

字段、超链接、脚注、尾注、批注和修订 API 位于 featherdoc::Document 上。 其中可以限定到正文、页眉、页脚或分节部件的字段和超链接操作，也可通过 featherdoc::TemplatePart 使用。

类型化签名导读

字段、超链接、脚注、批注和修订索引都从对应 list_* 方法返回，并从 0 开始。 append 类方法返回 std::size_t 时表示创建数量；返回 bool 的方法表示 指定索引条目是否成功修改。

签名	参数	返回语义
std::vector<field_summary> list_fields() const	无。	返回选中文档部件中的字段摘要。
bool append_field(std::string_view instruction, std::string_view result_text = {}, field_state_options state = {})	instruction：Word 字段指令。result_text：显示结果。state：dirty/locked 选项。	字段追加成功时返回 true。
bool replace_field(std::size_t field_index, std::string_view instruction, std::string_view result_text = {})	field_index：来自 list_fields() 的索引。instruction 和 result_text：替换值。	指定字段替换成功时返回 true。
std::size_t append_hyperlink(std::string_view text, std::string_view target)	text：可见超链接文本。target：URL 或关系目标。	返回创建的超链接数量；0 表示未追加。
std::size_t append_comment(std::string_view selected_text, std::string_view comment_text, std::string_view author = {}, std::string_view initials = {}, std::string_view date = {})	selected_text：被批注文本。comment_text：批注正文。元数据参数可选。	返回创建的批注数量；0 表示输入校验或修改失败。
bool set_comment_resolved(std::size_t comment_index, bool resolved)	comment_index：来自 list_comments() 的索引。resolved：目标状态。	批注状态更新成功时返回 true。
bool accept_revision(std::size_t revision_index)	revision_index：来自 list_revisions() 的索引。	指定修订接受成功时返回 true。
std::size_t accept_all_revisions()	无。	返回已接受的跟踪修订数量。

摘要类型

类型	关键字段	用途
featherdoc::field_summary	kind、instruction、result_text、dirty、locked	描述简单或复杂 Word 字段。
featherdoc::hyperlink_summary	text、target、anchor、external	描述内部或外部超链接。
featherdoc::review_note_summary	kind、author、date、resolved、text	描述脚注、尾注、批注和批注回复。
featherdoc::revision_summary	kind、author、part_entry_name、text	描述跟踪插入、删除以及相关修订记录。

字段

方法	返回值	用途
list_fields() const	std::vector<field_summary>	枚举选中文档部件中的字段。
append_field(instruction, result_text, state)	bool	追加简单字段指令和可选显示结果。
append_complex_field(instruction, result_text, options)	bool	追加复杂 Word 字段。
append_page_number_field(state = {})	bool	追加 PAGE 字段。
append_total_pages_field(state = {})	bool	追加 NUMPAGES 字段。
append_table_of_contents_field(options, result_text)	bool	追加 TOC 字段。
append_reference_field(bookmark_name, options, result_text)	bool	追加指向书签的 REF 字段。
replace_field(field_index, instruction, result_text)	bool	按索引替换字段指令和结果。

超链接

方法	返回值	用途
list_hyperlinks() const	std::vector<hyperlink_summary>	枚举超链接。
append_hyperlink(text, target)	std::size_t	追加超链接并返回创建数量；0 表示未追加超链接。
replace_hyperlink(hyperlink_index, text, target)	bool	替换超链接文本和目标。
remove_hyperlink(hyperlink_index)	bool	删除一个超链接。

脚注、批注和修订

方法	返回值	用途
list_footnotes() const / list_endnotes() const	std::vector<review_note_summary>	枚举脚注或尾注。
append_footnote(reference_text, note_text)	std::size_t	追加脚注。
append_endnote(reference_text, note_text)	std::size_t	追加尾注。
replace_footnote(note_index, note_text)	bool	替换一个脚注。
remove_endnote(note_index)	bool	删除一个尾注。
list_comments() const	std::vector<review_note_summary>	枚举批注。
append_comment(selected_text, comment_text, author, initials, date)	std::size_t	追加锚定到选中文本的批注。
append_text_range_comment(start_paragraph_index, start_text_offset, end_paragraph_index, end_text_offset, comment_text, author, initials, date)	std::size_t	为文本范围添加批注。
set_comment_resolved(comment_index, resolved)	bool	标记批注已解决或未解决。
list_revisions() const	std::vector<revision_summary>	枚举跟踪修订。
accept_revision(revision_index) / reject_revision(revision_index)	bool	接受或拒绝一个修订。
accept_all_revisions() / reject_all_revisions()	std::size_t	接受或拒绝全部修订。

示例

featherdoc::Document doc{"review.docx"};
doc.open();

auto body = doc.body_template();
body.append_page_number_field();
body.append_hyperlink("FeatherDoc", "https://github.com/wuxianggujun/FeatherDoc");

for (const auto &comment : doc.list_comments()) {
    if (!comment.resolved) {
        doc.set_comment_resolved(comment.index, true);
    }
}