electron in page search

Electron 應用程式的頁內搜索

該軟體包為 Electron 應用程式提供了 Chrome 的本機頁內搜尋功能。 Electron 將 Chrome 的原生 API 暴露給 JavaScript。但本機頁內搜尋 API 存在一些缺陷和狀態。所以這個包包裝了它並提供了更簡單、無陷阱的 API。

頁內搜尋可用於 Electron 應用程式中的瀏覽器視窗或 webview（ BrowserWindow實例或<webview>標籤）。在渲染器進程中，您只能對它們使用一個函數。

 // Pass current browser window's WebContents instance
const searchInWindow = searchInPage ( remote . getCurrentWebContents ( ) ) ;

// Pass <webview> instance
const searchInWebview = searchInPage ( document . getElementById ( 'my-webview' ) ) ;

// Open inner window made with <webview> for in-page search

// Search some text in the browser window
searchInWindow . openSearchWindow ( ) ;

// Search some text in the webview
searchInWebview . openSearchWindow ( ) ;

該軟體包可跨平台（macOS、Linux 和 Windows）運行，並在其上運行 CI（適用於 macOS 和 Linux 的 Travis CI，適用於 Windows 的 AppVeyor）。

安裝

 $ npm install --save electron-in-page-search

範例

新增了兩個範例。所以請在那裡查看工作應用程式的程式碼。

• 在瀏覽器視窗中搜尋
• 在<webview>中搜尋

您可以透過複製此儲存庫來嘗試它們。

 $ git clone https://github.com/rhysd/electron-in-page-search.git
$ cd electron-in-page-search
$ npm install
$ npm run build
$ npm run example # Run browser window example
$ cd example/webview/
$ npm start # Run webview example

您也可以查看現實世界的範例。

若要了解此套件的 API，您可以查看 TypeScript 的類型定義。

用法

當您想要在應用程式中使用頁內搜尋時，請呼叫searchInPage函數建立一個InPageSearch實例。

 import searchInPage from 'electron-in-page-search' ;
// or
const searchInPage = require ( 'electron-in-page-search' ) . default ;

import { remote } from 'electron' ;

const inPageSearch = searchInPage ( remote . getCurrentWebContents ( ) ) ;

document . getElementById ( 'some-button' ) . addEventListener ( 'click' , ( ) => {
    inPageSearch . openSearchWindow ( ) ;
} ) ;

當呼叫searchInPage時，它會為搜尋視窗建立一個<webview>元素。這個<webview>可以避免頁內搜尋找到搜尋視窗中的文字。

預設情況下，webview 有一個類別屬性electron-in-page-search-window search-inactive 。然後呼叫openSearchWindow ，webview 在搜尋時有一個類別屬性electron-in-page-search-window search-active 。因此，您可以透過 CSS 設定搜尋視窗 webview 的樣式，如下所示：

. electron-in-page-search-window {
  width : 300 px ;
  height : 36 px ;
  background-color : white;
}

. electron-in-page-search-window . search-inactive {
  visibility : hidden;
}

. electron-in-page-search-window . search-active {
  visibility : visible;
}

您可以透過background-color來控制搜尋視窗的背景顏色（上面指定了white ）。您可以進一步自訂 CSS（請參閱下面的「自訂」部分）。

請參閱範例的樣式以取得實例。

搜尋視窗包含「後退」按鈕、「前進」按鈕、「關閉」按鈕和查詢表單。應用程式使用者可以輸入查詢並點擊它們（或按表單中的回車鍵）開始頁內搜尋。重複按 Enter 鍵或按一下「後退」/「前進」按鈕可將焦點移至熱門單字。最後，用戶可以透過點擊「關閉」按鈕來關閉搜尋視窗以停止搜尋。

搜尋視窗關閉後，視窗的類別屬性將再次變為electron-in-page-search-window search-inactive 。

搜尋視窗<webview>安裝到document.body （或使用searchWindowParent選項指定的元素）。當您想要銷毀InPageSearch實例時，請確保呼叫.finalize()方法。它將從 DOM 中卸載搜尋視窗<webview> 。

發展

偵錯

如果您想查看 DevTools 的搜尋窗口，請將openDevToolsOfSearchWindow屬性傳遞給searchInPage函數，如下所示。

 searchInPage ( webContents , { openDevToolsOfSearchWindow : true } ) ;

它以分離模式開啟 DevTools。

而且這個包還支援日誌記錄。當$ELECTRON_IN_PAGE_SEARCH_DEBUG環境變數不為空時，它會在rendrer進程中以console.log輸出日誌。

打字稿

該套件是用 TypeScript 編寫的，並為 TypeScript 做好準備。您無需為此包準備類型定義文件，因為index.d.ts 已在此包中。

 import searchInPage , { InPageSearch } from 'electron-in-page-search' ;

let search : InPageSearch ;
const elem = document . createElement ( 'webview' ) ;
elem . src = 'https://example.com' ;

document . getElementById ( 'main' ) . appendChild ( elem ) ;
elem . on ( 'dom-ready' , ( ) => {
    search = searchInPage ( elem ) ;
} ) ;

document . getElementById ( 'search-button' ) . addEventListener ( 'click' , ( ) => {
    if ( search ) {
        search . openSearchWindow ( ) ;
    }
} ) ;

我的環境

我正在使用以下作業系統測試這個包

• macOS 10.12、OS X 10.11.6
• Ubuntu Linux 16.04 LTS
• 視窗8.1

客製化

使用我自己的 CSS 作為搜尋窗口

如果您想使用預設搜尋視窗但不想使用預設 CSS，則可以使用您自己的 CSS 檔案。

例如

 const path = require ( 'path' ) ;

searchInPage ( webview , {
    customCssPath : path . join ( __dirname , 'my_awesome_styles.css' )
} ) ;

下面是搜尋視窗中每個部件的class屬性清單。請為以下類別編寫您的 CSS 樣式。

類別名	描述	元素
inpage-search-body	整個搜尋視窗的主體	<div>
inpage-search-input	查詢表格	<input>
inpage-search-matches	“N/M”搜尋計數	<div>
inpage-search-back	「後退」按鈕	<div>
inpage-search-forward	「前進」按鈕	<div>
inpage-search-close	“關閉”按鈕	<div>

使用我自己的 HTML 作為搜尋窗口

如果您想控制整個搜尋窗口，您可以傳遞您自己的 HTML 檔案的路徑。

 const path = require ( 'path' ) ;

searchInPage ( webview , {
    customCssPath : path . join ( __dirname , 'my_awesome_styles.css' ) ,
    customSearchWindowHtmlPath : path . join ( __dirname , 'my_awesome_search_window.html' )
} ) ;

electro-in-page-search 套件注入<script>標籤來設定搜尋視窗<webview>和渲染器程序之間的 IPC 訊息傳遞。它會尋找每個元素並透過類別名稱設定偵聽器。

因此，您還需要在自己的搜尋視窗 HTML 中維護上述類別名稱。

搜尋的終身掛鉤

InPageSearch實例（從searchInPage傳回）擴展了EventEmitter 。它在某些時間發出一些事件。您可以掛鉤它們在某些時候執行您的程式碼。

下面是鉤子名稱的清單。

鉤子名稱	描述	監聽器參數
'打開'	窗戶打開時	()
'開始'	頁內搜尋開始	(query: string)
'下一個'	尋找下一場比賽時	(query: string, forward: boolean)
'焦點輸入'	專注於搜尋窗口	()
'成立'	與搜尋查詢相符的某些單字	(activeMatch: number, allMatch: number)

搜尋視窗的動畫

您可以使用 CSS 動畫來實現搜尋視窗的動畫。如果您不想在安裝 webview 時為搜尋視窗設定動畫，請使用search-firstpaint類別名，如下所示：

. electron-in-page-search-window . search-firstpaint {
  visibility : hidden;
}

. electron-in-page-search-window . search-inactive {
  animation-duration : 0.2 s ;
  animation-name : yourAwesomeAnimationOnClosing;
}

. electron-in-page-search-window . search-active {
  animation-duration : 0.2 s ;
  animation-name : yourAwesomeAnimationOnOpening;
}

第一次開啟搜尋視窗時， search-firstpaint類別將被刪除。

預加載搜尋窗口

InPageSearch實例延遲為搜尋視窗建立<webview>元素，直到先呼叫第一個openSearchWindow 。這在記憶體效率方面更好，因為<webview>分叉了一個新進程。

如果您想要事先載入搜尋窗口，請將preloadSearchWindow: true設定為searchInPage()呼叫的第二個參數。

執照

根據 MIT 許可證分發