搜索

Doconut Viewer 提供使用格式查看器提取的文本或基于文本的 PDF 重定向进行的普通搜索。它需要 Search 许可证功能。

启用搜索 UI

搜索是 Viewer 模块，而非独立工具栏。完整页面必须包含 Viewer 资源、Viewer 工具栏、Viewer 挂载点以及已初始化的 objViewer；随后会挂载并附加搜索功能区到同一实例。

搜索和注释是内置的授权功能，而非 AddPlugin<T>() 包。请从注入的 Viewer 请求搜索资源；只有在许可证授予搜索时才会发出它们的标签。

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true,
    IncludeSearchCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery = true,
    IncludeViewerScripts = true,
    IncludeSearchScripts = true,
    IncludeSearchBar = true
}))

嵌入的功能区调用与自定义 UI 相同的 JavaScript 方法。

在标记中保持完整的 Viewer 组合可见，首先初始化 docViewer，然后附加已授权的功能区：

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer 控件，包括打开 Search 的按钮 -->
</nav>
<div id="searchBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
    let searchBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        ResPath: 'doconut-res/images'
    });

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onStatus: (message) => console.log(message),
        onToast: (message, type) => console.log(type, message),
        onLayout: () => requestAnimationFrame(() => objViewer.Refit())
    });
    searchBar.attach(objViewer);
        </text>
    }
</script>

该组件注入 Find、Options 和 Results 组，并处理搜索、清除、匹配计数以及前后匹配导航。主机拥有的 Viewer 工具栏只需切换它：

searchBar.isOpen() ? searchBar.close() : searchBar.open();

它的公共 API 故意保持简洁：

可选的 onToggle(isOpen) 回调允许主机同步其搜索按钮，onLayout 允许在功能区高度变化时调整 viewer 的大小/重新适配。有关组合的 Viewer、Search 和 Annotation 启动顺序，请参阅 快速入门。

从 JavaScript 进行搜索

objViewer.Search(keyword, false, function (resultCount) {
    console.log('Matches:', resultCount);
});

第二个参数表示全词/精确匹配。回调之后：

中间件路由使用 search=<term> 和 exact=true|false 并返回 XML。请使用 widget API，而不是自行解析该内部响应。

检查搜索能力

初始化响应报告：

X-Doconut-Can-Search: 1

初始化后，objViewer.CanSearch() 显示相同的 format/session 判定。当服务器发送 0 时返回 false；在响应之前，或使用省略该标头的旧服务器时，默认返回 true。

三道独立的门不可混淆：

一种格式在技术上可能可搜索，但当前许可证拒绝该操作。

为每种格式启用提取

var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true   // 可选：让用户拖动一个区域并复制其文本
});

AllowSearch 和 AllowCopy 存在于 PdfConfig、WordConfig、ExcelConfig 和 PptConfig 上。Office 属性委托给其嵌套的 PdfConfig。两者默认均为 false。

常规原生搜索适配器支持 PDF、Word、Excel、PowerPoint、TXT、Visio、电子邮件、EPUB 和 MHT。XPS 默认使用其 PDF 路径。HTML 和 Microsoft Project 可受益于基于文本的 PDF 重定向：

// DefaultRender = false → 转换为基于文本的 PDF → 可搜索
var token = await viewer.OpenDocumentAsync(path, new HtmlConfig { DefaultRender = false });

对于原生渲染器，CanSearch() 描述了 viewer 的能力；但它并不保证特定文档包含可用文本。页面仅为扫描图像的 PDF 仍可能产生零原生结果。

正常搜索行为

服务器按以下顺序尝试搜索来源：

1. 来自格式原生 viewer 的结果。
2. 预构建的 .srh 搜索索引。
3. 当不存在搜索来源时返回错误/空结果。

.srh 索引是与页面图像一起发布的搜索产物，当文档从共享存储提供时，即使从未打开文档的节点也能回答搜索——参见 分布式部署。

即使特定的扫描文档没有文本层并因此返回零匹配，CanSearch() 对可搜索的 viewer 仍可能为 true。

许可和 UI 行为

有效的临时/演示许可证在其有效期内授予搜索功能。缺少许可证和旧版 TRIAL 文件则不授予搜索能力。没有搜索时：

• ReferenceCss 和 ReferenceScripts 省略搜索包。
• 中间件拒绝搜索，而不是返回已授权的结果。

通过 IDoconutLicenseService.IsCapabilityGranted(LicenseCapability.Search) 控制自定义 UI 可见性，并使用 CanSearch() 获取单独的 format/session 判定。

故障排查