# @epubjs-react-native/core 中文文档

规范地址：https://npmcn.com/package/%40epubjs-react-native/core/

版本：1\.4\.8
npm 元数据更新时间：2026-09-08T03:48:29.666Z
中文译文更新时间：2026-11-13T20:00:12.152Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40epubjs-react-native/core
原文对照：https://npmcn.com/package/%40epubjs-react-native/core/?lang=original
项目主页：https://github.com/victorsoares96/epubjs-react-native#readme
源码仓库：https://github.com/victorsoares96/epubjs-react-native

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.4 MB，107 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \*，react-native \*，react-native-webview \*，react-native-gesture-handler \*
- 首次发布：2022-08-11T15:55:01.874Z
- 最新版本发布：2026-09-08T03:48:29.487Z
- 近 30 天下载量：8363（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：105（近 12 个月 1 个）

## 中文简介

一个数字读取器,使用.opf.epub格式,在网页视图内使用epub.js库进行本地反应.

## 安装

```sh
npm install @epubjs-react-native/core
```

也可以使用：`pnpm add @epubjs-react-native/core`、`yarn add @epubjs-react-native/core`、`bun add @epubjs-react-native/core`

## README

# epubjs - 反应 - 内生

一个数字读取器,使用.opf.epub格式,在网页视图内使用epub.js库进行本地反应.

## 安装

```sh
npm install @epubjs-react-native/core
```

```sh
yarn add @epubjs-react-native/core
```

根据您想要应用此库的工程类型, 遵循以下步骤 :

#### 零安装

```sh
npm install @epubjs-react-native/file-system react-native-fs react-native-webview react-native-gesture-handler
```

```sh
yarn add @epubjs-react-native/file-system react-native-fs react-native-webview react-native-gesture-handler
```

#### 展览安装

```sh
npx expo install @epubjs-react-native/expo-file-system react-native-fs react-native-webview react-native-gesture-handler
```

#### 如果您为 iOS 开发, 请使用此命令安装 CocoaPods 道口( 如果您使用 expo 管理的项目, 您不需要此)

在您的 ios 项目文件夹中运行 :

```sh
npx pod-install
```

对于赤子反应本地项目,请添加以下权限: `Info.plist`数字 :

```sh
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
```

## 使用量

在 Reader Provider 中包入您的根组件 。 如果你有一个香草 React Industrial 的项目,一个好主意是把它添加到被传递到 App Registry 的组件中. 编译器。 这通常会出现在index.js文件中. 如果有会展项目,可以在App.js文件中的导出组件内完成.

```tsx
import * as React from 'react';
import { AppRegistry } from 'react-native';
import { ReaderProvider } from '@epubjs-react-native/core';
import { name as appName } from './app.json';
import App from './src/App';

export default function Main() {
  return (
    <ReaderProvider>
      <App />
    </ReaderProvider>
  );
}

AppRegistry.registerComponent(appName, () => Main);
```

这个 `<ReaderProvider>` 构成部分提供 `<Reader>` 框架所有组成部分的操作方法. **没有这个 `useReader` 钩子不通.**

在上述步骤之后,您可以将阅读器初始化如下:

```tsx
import * as React from 'react';

import { SafeAreaView } from 'react-native';
import { Reader, useReader } from '@epubjs-react-native/core';
// import { useFileSystem } from '@epubjs-react-native/file-system'; // for Bare React Native project
// import { useFileSystem } from '@epubjs-react-native/expo-file-system'; // for Expo project

export default function App() {
  const { goToLocation } = useReader();
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <Reader
        src="https://s3.amazonaws.com/moby-dick/OPS/package.opf"
        fileSystem={useFileSystem}
      />
    </SafeAreaView>
  );
}
```

## 阅读器参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `src` | `string` | 可能是一个 `base64`, (中文(简体) ), `epub`, (中文(简体) ), `opf`要求. |
| `width` | `number` `string` | EPub租借的宽度. 可选的. |
| `height` | `number` `string` | EPub租借地的高度. 可选的. |
| `fileSystem` | `function` | 返回 a 的函数 `FileSystem` 对象。 要求. |
| `initialLocation` | `ePubCfi` | 可以是ePubCfi或章节url. 可选的. |
| `enableSwipe` | `boolean` | 启用刷新动作 。 默认是 `true`。 。 。 . |
| `enableSelection` | `boolean` | 启用书上文本选择功能 。 默认是 `true`。 。 。 . |
| `onSwipeLeft` | `function` | 检测到左手势时调用 。 可选的. |
| `onSwipeRight` | `function` | 检测到刷取右手势时调用 。 可选的. |
| `renderLoadingFileComponent` | `JSX.Element` | 书装入时放出. 可选的. |
| `renderOpeningBookComponent` | `JSX.Element` | 书被渲染的时候看起来 可选的. |
| `onStarted` | `function` | 书载起后即召入. 可选的. |
| `onReady` | `function` | 书一展出就叫了 可选的. |
| `onDisplayError` | `function` | 书籍未显示时调用 。 可选的. |
| `onRendered` | `function` | 放弃吧,已经做了一个部分。 可选的. |
| `onChangeSection` | `function` | 更改区域时调用 。 可选的. |
| `onResized` | `function` | 更改页面时调用 。 可选的. |
| `onLocationChange` | `function` | 更改页面时调用 。 可选的. |
| `onSearch` | `function` | 在书被搜出后召去一次. 可选的. |
| `onLocationsReady` | `function` | 位置生成后立即调用 。 可选的. |
| `onSelected` | `function` | 文本选择发生后立即调用 。 可选的. |
| `onOrientationChange` | `function` | 检测到屏幕方向变化时调用 。 可选的. |
| `onPress` | `function` | 书被按下时召入. 可选的. |
| `onDoublePress` | `function` | 书被双按时叫来. 可选的. |
| `onBeginning` | `function` | 当书在主页上被调用. 可选的. |
| `onFinish` | `function` | 书入出后召入. 可选的. |
| `onLayout` | `function` | 书版式改变时调用. 可选的. |
| `defaultTheme` | `object` | 主题对象. 可选的. |
| `allowScriptedContent` | `boolean` | 允许在沙盒上运行脚本内容 . _Android 的默认是虚假的, 在 iOS 中是真实的_ |
| `allowPopups` | `boolean` | Epubjs 正在将 epub 内置内容和 iframe 默认为 sandbox = “ allow- same- generous ” , 以便打开链接或运行 javascript 在 epub 中, 您需要通过这个参数 . |
| `onPressExternalLink` | `function` | 外部链接按下时引用的函数 。 使用时 `allowPopups` 属性自动启用 |
| `menuItems` | `array` | 选择文本时将显示的一系列对象。 空阵列会压制菜单 . |
| `onAddAnnotation` | `function` | 在书中添加注释时引用的函数 . |
| `onChangeAnnotations` | `function` | 当注释数组被修改时引用的函数 . |
| `onPressAnnotation` | `function` | 按下注释时引用的函数 . |
| `initialAnnotations` | `array` | 用于装入本并附有说明 |
| `onAddBookmark` | `function` |  |
| `onRemoveBookmark` | `function` |  |
| `onRemoveBookmarks` | `function` |  |
| `onUpdateBookmark` | `function` |  |
| `onChangeBookmarks` | `function` | 修改书签数组时引用的函数 . |
| `initialBookmarks` | `array` | 渲染书后装入书签 |
| `injectedJavascript` | `string` | 提供书后会被注入的JavaScript. |
| `getInjectionJavascriptFn` | `function` | 提供注入 Javascript 函数, 与 WebView 函数相同 |
| `onWebViewMessage` | `function` | 网络视图事件收听器, 与网络视频相同 |
| `manager` | `default` `continuous` |  |
| `flow` | `auto` `paginated` `scrolled` `scrolled-doc` `scrolled-continuous` |  |
| `snap` | `boolean` |  |
| `spread` | `auto` `none` `always` |  |
| `fullsize` | `boolean` |  |
| `waitForLocationsReady` | `boolean` | 仅在生成位置后渲染书本 |
| `keepScrollOffsetOnLocationChange` | `boolean` | 更改位置时防止滚动顶部。 与 `scrolled-doc` 流动. |
| `charactersPerLocation` | `number` | 默认为 1600 |

## 钩子

#### 使用读取器

`useReader()` 是一个定制的钩子,它将返回所有书的状态和帮助你的方法. **确定您在阅读器中使用**

```tsx
const { changeFontSize, goToLocation, ... } = useReader();
```

##### 方法

| 方法 | 接收 | 说明 |
| --- | --- | --- |
| `changeFontSize` | `size` | 更改书中所有元素的字体大小 。 可能是一个px,pt或%. |
| `changeFontFamily` | `font` | 更改书中所有元素的字体家族 |
| `goToLocation` | `cfi` | 转到书中的特定位置 |
| `getLocations` |  | 获取书的总位置 |
| `goPrevious` | `PaginateOptions` | 转到书中上一页 |
| `goNext` | `PaginateOptions` | 转到书中的下一页 |
| `search` | `query` | 搜索书中的特定文本 |
| `clearSearchResults` | `void` | 清除搜索结果 |
| `changeTheme` | `theme` | 更改活动主题 |
| `getCurrentLocation` |  | 返回书的当前位置 |
| `getMeta` |  | 返回包含该书元数据的对象. |
| `addAnnotation` | `annotation` | 在书中附上注释. |
| `addAnnotationByTagId` | `annotation` | 在书中附上由 dom 元素标记 id 编写的注释 . |
| `updateAnnotation` | `annotation, data, styles` | 更新注释数据和样式 |
| `updateAnnotationByTagId` | `annotation, data, styles` | 通过 domm 元素标记 id 更新注释数据和样式 |
| `removeAnnotation` | `annotation` | 书中分出注释. |
| `removeAnnotationByTagId` | `annotation` | 书中用多姆元素标记id来解析注释. |
| `removeAnnotationByCfi` `cfi` |  | 书中的解析说明由提供cfi. |
| `removeAnnotations` | `type?: optional` | 解出书中所有注释. 可以按类型拆分 |
| `removeSelection` |  | 删除选择 |
| `addBookmark` | `bookmark` | 附加书签 |
| `updateBookmark` | `id, data` | 更新书签数据 |
| `removeBookmark` | `bookmark` | 删除书签 |
| `removeBookmarks` |  | 删除全部书签 |
| `injectJavascript` | `function` | 提供书后会被注入的JavaScript. |
| `changeFlow` | `Flow` | 将引渡的流量调整为相接或滚动(相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相 |

##### 国家

-   `theme`: 含有主题的对象.
-   `key`: 工作如书上独有的ID.
-   `atStart`:表示是否在书的开头.
-   `atEnd`:表示是否在书尾.
-   `currentLocation`:本作目前的位置.
-   `totalLocations`: 地点总数.
-   `progress`:本作的进展.
-   `isLoading`:表示书是否在装入.
-   `searchResults`: 搜索结果.
-   `meta`:包含本作元数据的对象.
-   `annotations`:包含本作注释的数组.
-   `section`:本作目前一节(章节).
-   `toc`: 也叫目录,是一份命令内容链接列表.
-   `landmarks`: 包含一系列主要内容
-   `bookmarks`: 包含书签的数组.
-   `isBookmarked`:显示当前位置是否为书签.

这个 `meta` 对象包含:

-   **覆盖** _(字符串、 矩阵缓冲、 无效或未定义)_:书的封面图像 `e.g.data:image/jpeg;base64,/9j/4AAQSkZJ...`
-   **作者** _(弦声)_: 该书的创作者/作者姓名 `e.g. Herman Melville`
-   **标题** _(弦声)_: 该书的标题 `e.g. Moby-Dick`
-   **说明** _(弦声)_:本作的描述/摘要.
-   **语言** _(弦声)_ : 该书的语言 `e.g. en-US`
-   **出版社** _(弦声)_:"电子书"出版社 `e.g. Harper & Brothers, Publishers`
-   **权利** _(弦声)_: 该书的权利 `e.g. This work is shared with the public using the Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) license.`

#### 实例

-   [您可以在这里看到实例演示](https://npmcn.com/package/%40epubjs-react-native/core/docs/EXAMPLES.md)
    
-   [在 Expo 项目上运行的实例](https://npmcn.com/package/%40epubjs-react-native/core/example-expo/App.tsx)
    
-   [在裸体反应原生项目上运行的实例](https://npmcn.com/package/%40epubjs-react-native/core/example-bare/App.tsx)
    

你喜欢这个项目吗? 考虑 [赞助](https://www.paypal.com/donate/?business=YNAUBS5LFN5KN&no_recurring=1&currency_code=USD) 计划要保持活力

## 许可证

麻省理工学院

## 常见问题

### @epubjs-react-native/core 是什么？

一个数字读取器,使用\.opf\.epub格式,在网页视图内使用epub\.js库进行本地反应\.

### 如何安装 @epubjs-react-native/core？

在项目目录运行 npm install @epubjs-react-native/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）、react-native-webview（\*）、react-native-gesture-handler（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @epubjs-react-native/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @epubjs-react-native/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @epubjs-react-native/core 可以商用吗？

@epubjs-react-native/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @epubjs-react-native/core 的下载量有多少？

根据 npm 官方下载统计，@epubjs-react-native/core 在 2026/10/14 – 2026/11/12 这 30 天内被下载 8,363 次，日均约 279 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @epubjs-react-native/core 还在维护吗？

最新版本 1\.4\.8 发布于 2026/09/08（2 个月前）；至今共发布 105 个版本，其中过去 12 个月发布了 1 个；首次发布于 2022/08/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。