閱讀服務使用示例（HarmonyOS Reader Kit）

Reader Kit到底能干啥？

第一次搞電子書閱讀器，真以為就是“讀txt顯示出來”這么簡單，結果各種格式、排版、翻頁動效、目錄跳轉……全是坑。還好有Reader Kit，救了我一命。寫這篇純粹是給后來人留點“血淚史”，也給自己留個念想。

都能干啥？

txt、epub、mobi、azw、azw3這些格式都能整，書名、作者、封面、目錄、正文全能拿。
txt、富文本（html+css）排版，仿真翻頁、橫滑分頁，排版快照啥都有。
閱讀頁組件（ReadPageComponent）負責內容顯示、翻頁交互、動效，進度感知也有。

用下來覺得爽的點

多格式解析，啥書都能讀，信息都能薅。
富文本排版快，支持自定義字體，W3C標準，兼容性不用愁。
翻頁動效真香，OpenGL加持，翻著翻著都想多看兩頁。

幾個繞不開的名詞

ReadPageComponent：閱讀頁UI組件，負責內容顯示、翻頁交互、進度感知。
BookParser：電子書解析引擎，啥格式都能啃。
spine（書脊）：不是你的后背，是書的閱讀順序，每個SpineItem是一個內容節點。

有啥坑/限制

只能讀本地文件，別想著在線書，云書架啥的暫時別想。
DRM保護的書，別折騰了，打不開。
只認txt、epub、mobi、azw、azw3，pdf啥的別拿來試。
排版和交互必須用ReadPageComponent，自己造輪子多半踩坑。
只支持HarmonyOS NEXT 5.0.4+的真機，模擬器別浪費時間。
只在大陸能用，港澳臺/海外暫時別想。

怎么拿到書名和封面？

有時候產品就想在書架上秀個封面和書名，其實Reader Kit拿這些信息很順手。

我一般這么寫（別忘了spineIndex，寫錯了封面就是一片空白，別問我怎么知道的）：

// 這段代碼抄過去基本能用，別忘了路徑和權限
import { bookParser } from '@kit.ReaderKit';
import { image } from '@kit.ImageKit';let path: string = './download/ebook/abc.epub';
let bookParserHandler: bookParser.BookParserHandler = await bookParser.getDefaultHandler(path);
let bookInfo: bookParser.BookInfo = bookParserHandler.getBookInfo();
let bookTitle = bookInfo.bookTitle;
let buffer: ArrayBuffer = bookParserHandler.getResourceContent(-1, bookInfo.bookCoverImage);
let imageSource: image.ImageSource = image.createImageSource(buffer);
let bookCover: image.PixelMap = await imageSource.createPixelMap();
imageSource.release();

怎么搞目錄和跳轉？

目錄、章節跳轉這些功能，產品肯定要。Reader Kit的目錄解析和跳轉還挺順。

我一般這么寫（目錄縮進別亂寫，catalogLevel用錯，目錄就成了“樓梯”）：

// 目錄渲染和跳轉，抄過去能跑，記得調試下縮進
import { bookParser } from '@kit.ReaderKit';
import { hilog } from '@kit.PerformanceAnalysisKit';@State catalogItemList: bookParser.CatalogItem[] = [];
private defaultHandler: bookParser.BookParserHandler | null = null;private async getCatalogItemList(){let path: string = './download/ebook/abc.epub';this.defaultHandler = await bookParser.getDefaultHandler(path);this.catalogItemList = this.defaultHandler.getCatalogList() || [];
}// 渲染目錄
build() {Column() {List() {ForEach(this.catalogItemList, (item: bookParser.CatalogItem) => {ListItem() {// ...章節名、點擊跳轉等...}})}}
}

跳轉章節：

private async jumpToCatalogItem(catalogItem: bookParser.CatalogItem){const domPos = await this.getDomPos(catalogItem);const resourceIndex = this.getResourceItemByCatalog(catalogItem).index;// 用domPos和resourceIndex跳轉
}private async getDomPos(catalogItem: bookParser.CatalogItem): Promise<string> {const domPos: string = this.defaultHandler?.getDomPosByCatalogHref(catalogItem.href || '') || '';return domPos;
}private getResourceItemByCatalog(catalogItem: bookParser.CatalogItem): bookParser.SpineItem {let resourceFile = catalogItem.resourceFile || '';let spineList: bookParser.SpineItem[] = this.defaultHandler?.getSpineList() || [];let resourceItemArr = spineList.filter(item => item.href === resourceFile);if (resourceItemArr.length > 0) {hilog.info(0x0000, 'testTag', 'getResourceItemByCatalog get resource ', resourceItemArr[0]);return resourceItemArr[0];}  else if (spineList.length > 0) {hilog.info(0x0000, 'testTag', 'getResourceItemByCatalog get resource in resourceList', spineList[0]);return spineList[0];} else {hilog.info(0x0000, 'testTag', 'getResourceItemByCatalog get resource in escape');return {idRef: '',index: 0,href: '',properties: ''};}
}

閱讀器怎么搭起來？

ReadPageComponent才是“靈魂”，翻頁、進度、交互全靠它。

第一次做閱讀器，沒等頁面渲染完就隱藏loading，結果用戶一進來先黑屏。記得加好加載狀態！

我一般這么寫：

// 下面這段直接抄，記得把路徑和參數換成自己的
import { bookParser, ReadPageComponent, readerCore } from '@kit.ReaderKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { display } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { common } from '@kit.AbilityKit';private readerComponentController: readerCore.ReaderComponentController = new readerCore.ReaderComponentController();
private readerSetting: readerCore.ReaderSetting = {fontName: '系統字體',fontPath: '',fontSize: 18,fontColor: '#000000',fontWeight: 400,lineHeight: 1.9,nightMode: false,themeColor: 'rgba(248, 249, 250, 1)',themeBgImg: '',flipMode: '0',scaledDensity: display.getDefaultDisplaySync().scaledDensity > 0 ? display.getDefaultDisplaySync().scaledDensity : 1,viewPortWidth: 370,viewPortHeight: 800,
};
private bookParserHandler: bookParser.BookParserHandler | null = null;
@State isLoading: boolean = true;// 構建閱讀組件
build() {Stack() {ReadPageComponent({controller: this.readerComponentController,readerCallback: (err: BusinessError, data: readerCore.ReaderComponentController) => {this.readerComponentController = data;}})Row() {Text('加載中...')}.width('100%').height('100%').justifyContent(FlexAlign.Center).backgroundColor(Color.White).visibility(this.isLoading ? Visibility.Visible : Visibility.None)}.width('100%').height('100%')
}// 打開書籍到指定進度
aboutToAppear(): void {let filePath: string = 'xxx/download/ebook/abc.epub';let spineIndex: number = 0;let domPos: string = '';this.registerListener();this.startPlay(filePath, spineIndex, domPos);
}private registerListener(): void {this.readerComponentController.on('pageShow', (data: readerCore.PageDataInfo): void => {hilog.error(0x0000, 'testTag', 'pageshow: data is: ' + JSON.stringify(data));if (data.state === readerCore.PageState.PAGE_ON_SHOW) {this.isLoading = false;}});
}private async startPlay(filePath: string, spineIndex: number, domPos: string) {try {let context = this.getUIContext().getHostContext() as common.UIAbilityContext;let initPromise = this.readerComponentController.init(context);let bookParserHandler = bookParser.getDefaultHandler(filePath);let result: [bookParser.BookParserHandler, void] = await Promise.all([bookParserHandler, initPromise]);this.bookParserHandler = result[0];this.readerComponentController.setPageConfig(this.readerSetting);this.readerComponentController.registerBookParser(this.bookParserHandler);this.readerComponentController.startPlay(spineIndex || 0, domPos);} catch (err) {hilog.error(0x0000, 'testTag', 'startPlay: err: ' + JSON.stringify(err));}
}aboutToDisappear(): void {this.readerComponentController.off('pageShow');this.readerComponentController.releaseBook();
}

想換字體？這樣搞

有時候產品一句“能不能換個字體”，開發就得支持自定義字體。字體文件可以放在resources/rawfile/fonts或沙箱路徑下，別忘了注冊resourceRequest回調，否則字體加載不出來。

我一般這么寫：

// 字體換起來，路徑別寫錯，回調別忘了
import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';let filePath: string = 'fonts/SourceHanSerifCN-VF.ttf';
// let filePath: string = this.getUIContext().getHostContext()!.filesDir + 'fonts/SourceHanSerifCN-VF.ttf';this.readerSetting.fontName = '思源宋體';
this.readerSetting.fontPath = filePath;
this.readerComponentController.setPageConfig(this.readerSetting);aboutToAppear(): void {this.readerComponentController.on('resourceRequest', this.resourceRequest);
}aboutToDisappear(): void {this.readerComponentController.off('resourceRequest');
}private isFont(filePath: string): boolean {let options = [".ttf", ".woff2", ".otf"];let path = filePath.toLowerCase();return options.some(ext => path.indexOf(ext) !== -1);
}private resourceRequest: bookParser.CallbackRes<string, ArrayBuffer> = (filePath: string): ArrayBuffer => {if(filePath.length === 0){return new ArrayBuffer(0);}let resourcePath = filePath;if(this.isFont(filePath)){resourcePath = 'fonts/' + resourcePath;}try {let context = this.getUIContext().getHostContext() as common.UIAbilityContext;let value: Uint8Array = context.resourceManager.getRawFileContentSync(resourcePath);return value.buffer as ArrayBuffer;} catch (error) {return this.loadFileFromPath(resourcePath);}
}private loadFileFromPath(filePath: string): ArrayBuffer {try {let stats = fs.statSync(filePath);let file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);let buffer = new ArrayBuffer(stats.size);fs.readSync(file.fd, buffer);fs.closeSync(file);return buffer;} catch (err) {return new ArrayBuffer(0);}
}

背景也能隨心換

想讓閱讀器更有個性？可以自定義背景色和背景圖片。設置淺色背景時，記得關掉夜間模式，字體顏色也要適配，否則白底白字啥都看不見。

我一般這么寫：

// 背景換起來，圖片和顏色都能玩，別忘了適配字體色
import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';this.readerSetting.themeColor = '#FFFFFF';
this.readerSetting.themeBgImg = '';
this.readerSetting.nightMode = false;
this.readerSetting.fontColor = '#000000';this.readerSetting.themeBgImg = 'white_sky_first.jpg';
this.readerSetting.themeColor = '#FFFFFF';
this.readerSetting.nightMode = false;
this.readerSetting.fontColor = '#000000';
this.readerComponentController.setPageConfig(this.readerSetting);aboutToAppear(): void {this.readerComponentController.on('resourceRequest', this.resourceRequest);
}aboutToDisappear(): void {this.readerComponentController.off('resourceRequest');
}private resourceRequest: bookParser.CallbackRes<string, ArrayBuffer> = (filePath: string): ArrayBuffer => {if(filePath.length === 0){return new ArrayBuffer(0);}try {let context = this.getUIContext().getHostContext() as common.UIAbilityContext;let value: Uint8Array = context.resourceManager.getRawFileContentSync(filePath);return value.buffer as ArrayBuffer;} catch (error) {return this.loadFileFromPath(filePath);}
}private loadFileFromPath(filePath: string): ArrayBuffer {try {let stats = fs.statSync(filePath);let file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);let buffer = new ArrayBuffer(stats.size);fs.readSync(file.fd, buffer);fs.closeSync(file);return buffer;} catch (err) {return new ArrayBuffer(0);}
}

深色/淺色切換別忘了

現在用戶都喜歡深色/淺色自由切換，Reader Kit也能動態適配。監聽colorMode變化，切換主題時記得同步字體色和背景色。

我一般這么寫：

// 主題切換，別忘了字體色和背景色一起改
import { Configuration, UIAbility } from '@kit.AbilityKit';
import { ConfigurationConstant } from '@kit.AbilityKit';export default class EntryAbility extends UIAbility {onConfigurationUpdate(newConfig: Configuration): void {AppStorage.setOrCreate('colorMode', newConfig.colorMode);}
}@StorageLink('colorMode') @Watch('colorModeChange') colorMode: ConfigurationConstant.ColorMode =ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET;colorModeChange() {if (this.colorMode === ConfigurationConstant.ColorMode.COLOR_MODE_DARK) {this.readerSetting.nightMode = true;this.readerSetting.fontColor = '#ffffff';this.readerSetting.themeColor = '#202224';} else {this.readerSetting.nightMode = false;this.readerSetting.fontColor = '#000000';this.readerSetting.themeColor = '#FFFFFF';}this.readerComponentController.setPageConfig(this.readerSetting);
}