当前位置：首页 > news >正文

阅读服务使用示例（HarmonyOS Reader Kit）

news 来源：原创 2025/6/27 10:10:02

阅读服务使用示例（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);
}