# @databiosphere/findable-ui 中文文档

规范地址：https://npmcn.com/package/%40databiosphere/findable-ui/

版本：61\.0\.0
npm 元数据更新时间：2026-11-11T05:23:21.531Z
中文译文更新时间：2026-11-11T13:50:07.689Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40databiosphere/findable-ui
原文对照：https://npmcn.com/package/%40databiosphere/findable-ui/?lang=original
项目主页：https://github.com/DataBiosphere/findable-ui/tree/main/#readme
源码仓库：https://github.com/DataBiosphere/findable-ui

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

- 包体积（解压后）：2.7 MB，3156 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：22\.13\.0
- 运行依赖：0 个
- peer 依赖：ky ^1\.10\.0，yup ^1\.7\.1，next ^16，uuid ^13\.0\.0，react ^19\.2\.3，slugify ^1\.6\.6，unified ^11\.0\.5，next-auth ^4\.24\.13，react-dom ^19\.2\.3，rehype-raw ^7\.0\.0，remark-gfm ^4\.0\.1，gray-matter ^4\.0\.3，react-window ^1\.8\.11，rehype-react ^8\.0\.0，remark-parse ^11\.0\.0，@mui/material ^7\.3\.6，remark-rehype ^11\.1\.2，@emotion/react ^11\.14\.0，@emotion/styled ^11\.14\.1，next-mdx-remote ^6\.0\.0，rehype-sanitize ^6\.0\.0，react-idle-timer ^5\.7\.2，copy-to-clipboard ^3\.3\.3，@observablehq/plot ^0\.6\.17，@mui/icons-material ^7\.3\.6，@tanstack/react-query ^5\.90\.12，@tanstack/react-table ^8\.21\.3，@tanstack/react-virtual ^3\.13\.13，yet-another-react-lightbox ^3\.32\.2，@tanstack/match-sorter-utils ^8\.19\.4
- 首次发布：2024-04-16T06:37:48.628Z
- 最新版本发布：2026-11-11T05:23:21.175Z
- 近 30 天下载量：3351（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：140（近 12 个月 46 个）

## 中文简介

-   `src` 包含 TypeScript 源文件; `lib` 将包含编译的 JavaScript,这是外部应用程序应当导入的内容。 - 外部应用程序使用的导入路径需要指定从软件包名称开始的完整路径,

## 安装

```sh
npm install @databiosphere/findable-ui
```

也可以使用：`pnpm add @databiosphere/findable-ui`、`yarn add @databiosphere/findable-ui`、`bun add @databiosphere/findable-ui`

## README

# 可找到的 - ui

## 一般资料

-   `src` 包含 TypeScript 源文件; `lib` 将包含编译的 JavaScript,它应该由 外部应用程序.
-   外部应用程序使用的导入路径需要指定从软件包名称开始的完整路径, 报告格式 `@databiosphere/findable-ui/lib/<path>`时 `<path>` 是文件在 `lib` 文件夹.

## 从Next.js 15到16

本节为将可找到的自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自去自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自 详细线路在 [Next.js的消费者设置 16](https://npmcn.com/package/%40databiosphere/findable-ui/#readme-consumer-setup-for-nextjs-16-pages-router-static-export) 下面;本节讲述消费回购中需要改变的一切.

> **关于可找到- ui 的同位素范围的说明 :** 寻取-i's `next` 端点被绑定到 `^16` (无) `^15.5.13 || ^16`) (中文(简体) ). 没有v15倒计时——消费者必须移动到下十六去取匹配的可找到的-ui放出.

### 1\. 附带依赖关系

-   `next` → `^16`
-   `eslint-config-next` → `^16`
-   `@next/eslint-plugin-next` → `^16`
-   `next-mdx-remote` → `^6` (findable-ui的非可选对等分解——即使您的消费者没有直接制取MDX,或者您会得到对等分解警告并找到可找到的-ui的MDX帮助器会被打破,也必须被撞倒)
-   `@databiosphere/findable-ui` 船舶的释放 `^16` 端点
-   安装 MUI 的情感助手( 新 ) : `npm install @mui/material-nextjs @emotion/server`

### 2\. 抽出节点基准

设置工程的节点版本为 `22.13.0` (最新数据) `.nvmrc`、 CI 工作流程以及任何 Docker 文件 `FROM node:...` 页:1.

### 3\. 连接MUI情感缓存

要求避免在MUI类组件上发生回水分警告. 更新 `pages/_app.tsx` 与 `AppCacheProvider` 财务报告和审定财务报表 `pages/_document.tsx` 与 `DocumentHeadTags` + 键 `documentGetInitialProps` - 准确的片段英寸 [Next.js的消费者设置 16](https://npmcn.com/package/%40databiosphere/findable-ui/#readme-consumer-setup-for-nextjs-16-pages-router-static-export)。 。 。 .

### 4\. 建起网包

变动 `next dev` 财务报告和审定财务报表 `next build` 援引 `package.json` 脚本到 `next dev --webpack` 编号 : `next build --webpack`.涡轮包装+页路由器+MUI在上游被打破——见 [涡轮包选择退出](https://npmcn.com/package/%40databiosphere/findable-ui/#readme-opt-out-of-turbopack-required-for-now) 追踪问题说明.

### 5\. 最新情况 `next-mdx-remote/serialize` 电话

如果你的消费者打电话 `serialize()` 直接(即不通过可找到的-i's `buildStaticProps` 助手,通过 `blockJS: false`。见 [说明 `next-mdx-remote@6`](https://npmcn.com/package/%40databiosphere/findable-ui/#readme-note-on-next-mdx-remote6) 为什么.

### 6\. 将ESLint迁移到平面配置

下十六个删除 `next lint` 和 v16 配置包的目标平面配置 。 替换 `.eslintrc.json` 与 `eslint.config.mjs`; 可找到的 - i 自己的 `eslint.config.mjs` 是一种参考执行。 替换任何 `next lint` cI中的援引 `npx eslint .` (或等同为一.

### 7\. 联合国. `next/router` - 不需要移徙

下十六页路由器仍然完全支持 `next/router`。 。 。 . **消费者不需要自己迁徙 `next/router` 电话网站.** 找到 - i 自己留着 `next/router` 在呼叫地点 `next/navigation` 这不是一个干净的交换,这是故意的,是支持的.

### 正在验证

-   `next build --webpack` 成功 .
-   浏览器控制台显示在可找到的-ui-已发送的页面上没有反应水合警告.
-   通过JSX表达式属性(如. `<Breadcrumbs breadcrumbs={[...]} />`)仍然收到他们的道具.
-   单位+ Playwright e2e套房通过.

### 发布参考

寻找- i 的 ChangGELOG 由 [请放行](https://github.com/googleapis/release-please) 从常规的委员会。 接下来的16个对等碰撞地在发行中,其变换GELOG条目包括: `chore!: next.js 16 prep: pin 'next' peer dep to ^16`;让消费者相信这个版本或以后.

* * *

## Next.js 16的消费者设置(Pages路由器,静态导出)

在 Next.js 16 上关闭的应用程序必须连接 MUI 的情感缓存助手 `_app.tsx` 财务报告和审定财务报表 `_document.tsx`. 没有这种接线,浏览器将报告由MUI + 情感(多为可找到-ui)所风格的组件上的回放水分警告.

### 术语说明

此设置涉及一个名为软件包 `@mui/material-nextjs` 和一位援助者 `documentGetInitialProps`。命名使用"SSR"/"文档"术语,因为软件包一般针对Next.js,包括运行运行时的HTTP服务器的部署. **它仍然适用于静态出口部署.** 下文所述的所有工作均在 `next build` 时间,在同一步骤产生静态 `.html` 文档。 没有涉及运行时服务器 .

当docs说"服务器上的摘录样式"时,读作"静态HTML构建步骤期间的摘录样式"

### 为什么需要这个

-   可找到-ui组件被以MUI + Emotion(CSS-in-JS)为样式.
-   情感产生 `css-XXXXXXX` 分类名称,以散列样式排列,顺序在React渲染树行走时首次遇到.
-   Next.js 通过运行一次反应树来构建静态 HTML `next build`,然后浏览器在水合过程中再次运行同一树. 水合能成功,两道通路必须产生同等名.
-   在下16下(Turbopack是默认的捆绑器),构建过程中的模块评价顺序可以与浏览器中的顺序相去甚远,因此同一组件可以在每通路口上指定不同的散列. 19反应报告这是水合不匹配.
-   修补:在构建的 HTML 生成步骤中捕捉情感的风格缓存并注入由此产生的 `<style>` 标记输入静态 HTML。 然后浏览器将水合物与建筑所写的确切类名相抗衡.

### 所需软件包

在消耗项目中安装 :

```bash
npm install @mui/material-nextjs @emotion/server
```

-   `@mui/material-nextjs` – MUI 的官方集成包;提供缓存提供者和文档头提取器
-   `@emotion/server` ——文档帮助器的对等依赖;在构建过程中用于将情感风格冲入 HTML

### 切出涡轮包( 目前需要)

接下来的16年让Turbopack成为默认的捆绑商. Turbopack + Pages 路由器 + MUI 目前被打破——情感类名称在静态HTML和浏览器水合通路口之间相去甚远,产生了本节意在修复的准确水合不匹配. 上面的接线仍然需要,但是在涡轮包下不起作用.

直到上游固定土地为止[vercel/next.js#82607 (英语)](https://github.com/vercel/next.js/issues/82607)),指针 `next dev` 编号 : `next build` 引用网页包:

```jsonc
// package.json
"scripts": {
  "dev": "next dev --webpack",
  "build": "next build --webpack"
}
```

Webpack在"下16"中仍然得到充分支持——涡轮包装被提升为默认,而不是"webpack被移除". 网包倒置的贬值时间表尚未公布,但 `--webpack` 旗帜是一个临时工作,预计今后将取消. **订阅 [vercel/next.js#82607 (英语)](https://github.com/vercel/next.js/issues/82607) 申请地位**,并当 Next.js 发布网络包去除通知或上游涡轮包 + Pages 路由器 + MUI 错误解析时审查此接针.

这是Next.js / Turbopack bug, 不是可找到的一。 可重新使用的涡轮包装 [vercel/next.js#82607 (英语)](https://github.com/vercel/next.js/issues/82607) 关闭.

### `_app.tsx`

将应用程序包入 `AppCacheProvider`数字 :

```tsx
import { AppCacheProvider } from "@mui/material-nextjs/v16-pagesRouter";
import type { EmotionCache } from "@emotion/react";
import type { AppProps } from "next/app";
import type { JSX } from "react";

type MyAppProps = AppProps & {
  emotionCache?: EmotionCache;
};

function MyApp(props: MyAppProps): JSX.Element {
  const { Component, emotionCache, pageProps } = props;
  return (
    <AppCacheProvider emotionCache={emotionCache}>
      {/* existing theme providers and layout */}
      <Component {...pageProps} />
    </AppCacheProvider>
  );
}

export default MyApp;
```

### `_document.tsx`

添加 `DocumentHeadTags` 内部 `<Head>` 并指定 `documentGetInitialProps` 作为静态 `getInitialProps`数字 :

```tsx
import {
  documentGetInitialProps,
  DocumentHeadTags,
} from "@mui/material-nextjs/v16-pagesRouter";
import type { DocumentHeadTagsProps } from "@mui/material-nextjs/v16-pagesRouter";
import Document, { Head, Html, Main, NextScript } from "next/document";
import type { DocumentContext } from "next/document";
import type { JSX } from "react";

class MyDocument extends Document<DocumentHeadTagsProps> {
  render(): JSX.Element {
    return (
      <Html>
        <Head>
          <DocumentHeadTags {...this.props} />
          {/* other head content */}
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

MyDocument.getInitialProps = async (ctx: DocumentContext) => {
  return await documentGetInitialProps(ctx);
};

export default MyDocument;
```

### 说明 `next-mdx-remote@6`

消费者使用 `next-mdx-remote` 使 MDX 内容必须通过 `blockJS: false` 改为 `serialize()`。第6版增加了一个 `blockJS: true` 默认在编译过程中会从 MDX 中剥去所有 JavaScript 表达式 — 包括 JSX 属性表达式, 如 `<Breadcrumbs breadcrumbs={[...]} />`。默认情况下,这些道具会在构建时静静地投放,接收部件则没有道具。 设置 `blockJS: false` 保存表达式值属性。 较窄 `blockDangerousJS: true` 设置( 默认) still 块 `eval` 编号 : `new Function` /等,因此保留了实际危险图案的安全网.

```ts
import { serialize } from "next-mdx-remote/serialize";

const mdxSource = await serialize(content, {
  blockJS: false,
  // ...your existing options
});
```

如果你使用可找到的-i's `buildStaticProps` 帮助( e)`@databiosphere/findable-ui/lib/utils/mdx/staticGeneration/staticProps`, (中文(简体) ), `blockJS: false` 已经是默认——不需要消费者改变.

### 删除 stale (已删除) `glob` 覆盖

一些消费者增加了以下区块: `package.json` 2025年末,将处理 `npm audit` 从Next.js 14的中转道岔中得出的结果:

```jsonc
"overrides": {
  "glob": "^11.0.4"
}
```

有了下16和目前的Dep图,这个覆接功能已经不再做有用的活了,事实上是默默地降级了较新的Glob消费者(例如. `@joshwooding/vite-plugin-react-docgen-typescript`,声明 `glob ^13`) (中文(简体) ). 截止2026-06-03, `npm audit` 调查结果没有按已解决的版本分类`glob@7.2.3`, (中文(简体) ), `glob@11.1.0`, (中文(简体) ), `glob@13.0.6`) ——自咨询地貌变化后,重新检查升级情况.

如果你的消费者带着这个功能, 移除块 `package.json` 运行 `npm install` 要刷新锁文件。 期待 `npm warn deprecated` 警告时间 `glob@7.x` (维护者在v9前标记为已贬值)和 `inflight@1.0.6` (通过Jest 29的中转链重新引入). 两者都是警告,而不是构建/CI失败.

## 开发可找到的自来水,同时开发消耗性应用

使用 `scripts/link.sh` 以建立和安装本地可找到的- ui 副本 进入一个消耗性项目(例如 ncpi-dataset-catalog,数据浏览器) :

1.  将这个寄存器复制到与消费应用程序相同的父文件夹中 .
    
2.  设定 `node` 版本为 `22.13.0`。 。 。 .
    
3.  运行 `npm install` 在两个仓库.
    
4.  从消耗性项目目录:
    
    ```bash
    ../findable-ui/scripts/link.sh
    ```
    
    这将编译为 TypeScript, 将输出装入, 安装到 `node_modules`,清除 Next.js 缓存,并启动 Dev 服务器.
    
5.  切换: Dev 服务器的 Ctrl+C, 更改可找到的- ui,以及 重放剧本.
    
6.  要恢复已发布的版本 :
    
    ```bash
    ../findable-ui/scripts/unlink.sh
    ```
    

消费项目可选择在其中添加薄薄的包装 `package.json` 脚本 :

```json
{
  "scripts": {
    "link-findable": "../findable-ui/scripts/link.sh",
    "unlink-findable": "../findable-ui/scripts/unlink.sh"
  }
}
```

## 常见问题

### @databiosphere/findable-ui 是什么？

src 包含 TypeScript 源文件; lib 将包含编译的 JavaScript,这是外部应用程序应当导入的内容。 - 外部应用程序使用的导入路径需要指定从软件包名称开始的完整路径,

### 如何安装 @databiosphere/findable-ui？

在项目目录运行 npm install @databiosphere/findable-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ky（^1\.10\.0）、yup（^1\.7\.1）、next（^16）、uuid（^13\.0\.0）、react（^19\.2\.3）、slugify（^1\.6\.6）、unified（^11\.0\.5）、react-dom（^19\.2\.3）、rehype-raw（^7\.0\.0）、remark-gfm（^4\.0\.1）、gray-matter（^4\.0\.3）、react-window（^1\.8\.11）、rehype-react（^8\.0\.0）、remark-parse（^11\.0\.0）、@mui/material（^7\.3\.6）、remark-rehype（^11\.1\.2）、@emotion/react（^11\.14\.0）、@emotion/styled（^11\.14\.1）、next-mdx-remote（^6\.0\.0）、rehype-sanitize（^6\.0\.0）、react-idle-timer（^5\.7\.2）、copy-to-clipboard（^3\.3\.3）、@mui/icons-material（^7\.3\.6）、@tanstack/react-query（^5\.90\.12）、@tanstack/react-table（^8\.21\.3）、@tanstack/react-virtual（^3\.13\.13）、@tanstack/match-sorter-utils（^8\.19\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @databiosphere/findable-ui 支持 TypeScript 吗？

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

### @databiosphere/findable-ui 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @databiosphere/findable-ui 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js 22\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @databiosphere/findable-ui 可以商用吗？

@databiosphere/findable-ui 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @databiosphere/findable-ui 的下载量有多少？

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

### @databiosphere/findable-ui 还在维护吗？

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