# @girder/components 中文文档

规范地址：https://npmcn.com/package/%40girder/components/

版本：4\.0\.2
npm 元数据更新时间：2026-05-18T14:51:06.092Z
中文译文更新时间：2026-11-16T09:50:05.094Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40girder/components
原文对照：https://npmcn.com/package/%40girder/components/?lang=original

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

- 包体积（解压后）：19 MB，76 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：12 个
- 首次发布：2018-09-17T13:10:09.965Z
- 最新版本发布：2026-05-18T14:51:05.950Z
- 近 30 天下载量：3298（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 4 个）

## 中文简介

试试看 [演示应用](https://gwc.girder.org/)它与 [数据. kitware.com](https://data.kitware.com/)。 。 。 .

## 安装

```sh
npm install @girder/components
```

也可以使用：`pnpm add @girder/components`、`yarn add @girder/components`、`bun add @girder/components`

## README

# Girder 网络组件库

试试看 [演示应用](https://gwc.girder.org/)。 。 。 . 和我们一起工作 [数据. kitware.com](https://data.kitware.com/)。 。 。 .

## 用法快速启动

**最新版本仅支持Vue3. 对于Vue2, [@ girder/ 组件 v3.3. 0](https://github.com/girder/girder_web_components/releases/tag/v3.3.0) 应当使用.**

### 安装

[维特](https://vite.dev/) 用于Girder网络组件的建筑应用程序.

```bash
# Install GWC
yarn add @girder/components
# or
npm install @girder/components
```

### 初始化

自由输出 [组件](https://npmcn.com/package/%40girder/components/src/components/) (单位:千美元) [插件](https://npmcn.com/package/%40girder/components/src/plugins/index.js) 缩写为 [暂停](https://npmcn.com/package/%40girder/components/src/utils/restClient.js) (单位:千美元) [通知窗口](https://npmcn.com/package/%40girder/components/src/utils/notificationBus.js),并注册 Vuetify 配置。 它可以选择注册所有组件.

使用插件的应用程序初始化示例( 通常为 `src/main.js`:

```javascript
/* src/main.js */
import { createApp } from 'vue'
import App from './App.vue'

import GirderPlugin from '@girder/components'

const app = createApp(App)

app.use(GirderPlugin, {
  girder: {apiRoot: import.meta.env.VITE_API_ROOT},
  notification: {useEventSource: true},
  components: true // register all components
})
app.mount('#app')
```

### 使用组件

所有组件都是前缀 `Girder`。 。 。 .

#### A-la-carte(建议)

在这种情况下,插件不会对所有组件进行注册,因此要单独使用组件,它们应该从名称导入 `@girder/components/`,因为这个位置在释放物之间是稳定的. 例如:

```javascript
import { GirderUpload } from '@girder/components/'; // Good
import { Upload } from '@girder/components/src/components/Upload/Upload.vue'; // Unsafe -- may move in the future
```

由于 Girder 网络组件使用 Vuetify, 您的应用程序必须提供 [`v-app` 财务报告和审定财务报表 `v-content` 集装箱](https://vuetifyjs.com/en/framework/default-markup#all-about-app) 在某种祖先层面.

例如,在 `src/App.vue`数字 :

```html
<!-- src/App.vue -->
<template>
  <v-app>
    <v-content>
      <h1>Welcome {{ currentUserLogin }}</h1>
      <GirderAuthentication />
    </v-content>
  </v-app>
</template>

<script setup>
import { inject, computed } from 'vue';
import { GirderAuthentication } from '@girder/components/';

// Injecting 'rest' is not necessary to use the component,
// but is required to access the results of API calls
const { rest, user } = inject('girder');
const currentUserLogin = computed(() => user.value ? user.value.login : 'anonymous');
</script>
```

#### 全球登记

在这种情况下,组件由插件注册,所以不需要被导入. 见 [演示应用程序](https://npmcn.com/package/%40girder/components/demo/App.vue) 更全面的例子.

## 高级使用

### 自定义 Vuetify 配置

自定义额外 vuetify 配置可以通过 `vuetifyConfig` 选项. 如果您的下游应用程序也在使用 Vuetify 并需要通过额外的配置 选项,必须注意与Girder网络组件相协调.

```javascript
/* src/main.js */
import { createApp } from 'vue'
import App from './App.vue'

import GirderPlugin from '@girder/components'

const app = createApp(App)

app.use(GirderPlugin, {
  girder: {apiRoot: import.meta.env.VITE_API_ROOT},
  notification: {useEventSource: true},
  vuetifyConfig: {icons: {aliases: {login: 'mdi-circle' }}}
})
app.mount('#app')
```

> **说明:** 你必须使用Mdi图标包。 图标包不能混合 .

### 其他安装方法

无需自己安装Girder网络组件,可以导入预建的捆绑.

#### 使用 CDN/UMD 软件

```html
<script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
<script src="https://unpkg.com/@girder/components"></script>
<link rel="stylesheet" href="https://unpkg.com/@girder/components/dist/style.css">
<script>
  const app = Vue.createApp({});
  app.use(girder);
  app.mount('#app');
</script>
```

这将曝光全局变量下的插件 `girder`。 。 。 .

#### 使用无害环境管理

```html
<script type="module">
import Gwc, { GirderUpload } from 'https://unpkg.com/@girder/components?module';

const app = Vue.createApp({});
app.use(Gwc);
app.component('GirderUpload', GirderUpload);
app.mount('#app');
</script>
```

## 对于开发者

```bash
# Project Setup
yarn

# Compile and hot-reload for development
yarn serve

# Build the library for production
yarn build

# Lint and fix source code
yarn lint
yarn lint:style

# Run unit tests
yarn test:unit
```

### 使用外部 Girder API

要针对外部 Girder API 构建演示应用程序,请设置 `VITE_API_ROOT` 环境变量。 例如:

```bash
export VITE_API_ROOT=https://data.kitware.com/api/v1
yarn serve
```

此可变值默认为 `http://localhost:8080/api/v1` 页:1 正常开发(假设开发者有本地实例) girder API 服务器正在运行). 当运行在您自己的 Girder API 服务器上时, 确定设置 [(简体中文)](https://girder.readthedocs.io/en/stable/security.html#cors-cross-origin-resource-sharing) 相应.

### 在页面上显示来自 Girder 的私人媒体

如果您的应用程序使用 `img` 或者说 `video` 从Girder装入的元素,有几个要求.

-   你必须使用 `authenticateWithCredentials` 选项.
-   您必须修改 [Girder 的 CORS 允许的源设置](https://girder.readthedocs.io/en/stable/security.html?highlight=cors#cors-cross-origin-resource-sharing) 和你的应用程序的原产地完全吻合 您可以使用逗号分隔列表来匹配多个来源, 例如 `*, http://localhost:8080, https://myapp.domain.com`
-   要与帆布或联署材料中装入的元素数据互动,可能需要添加 [横跨奥里金属性](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/crossOrigin) 对媒体元素.

### 部署和出版

演示应用自动部署到 [gwc.girder.org (英语)](https://gwc.girder.org/)。 。 。 .

任何贡献者都可以要求更新已出版的 npmjs 版本,方法是在其中更改版本字符串 `package.json` 并打开拉取请求。 我们的CI跑者会探测到变化 并在合并时公布 版本更新的PR一般应当独立于功能性PR.

### 类型定义

TypeScript 类型 def 维持在 `index.d.ts`。如果您的更改会影响公共 api,请记住更新此文件 .

## 常见问题

### @girder/components 是什么？

试试看 演示应用它与 数据\. kitware\.com。 。 。 \.

### 如何安装 @girder/components？

在项目目录运行 npm install @girder/components，或使用 pnpm add / yarn add / bun add。

### @girder/components 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/girder\_\_components 是否存在。

### @girder/components 支持 ESM 还是 CommonJS？

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

### @girder/components 可以商用吗？

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

### @girder/components 的下载量有多少？

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

### @girder/components 还在维护吗？

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

