ArtHub Web SDK

ArtHub Web SDK 是一个用于 ArtHub 网盘系统的前端 JavaScript SDK，提供文件上传和下载功能。

安装

npm install arthub-web-sdk

使用

import ArtHubWebSDK from 'arthub-web-sdk';
import { getConfigByName } from 'arthub-web-sdk';

// 初始化 SDK
const sdk = new ArtHubWebSDK({
  serviceConfig: getConfigByName('oa_test'), // 使用预定义配置
  token: 'your-token-here', // 从登录组件获取的 token
});

// 方式1：按节点ID上传文件
const result = await sdk.uploadFile({
  depot: 'test',
  file: fileObject, // File 对象
  parentNodeId: 123456, // 可选：父节点 ID
  onProgress: (completed, total) => {
    console.log(`上传进度: ${(completed / total * 100).toFixed(1)}%`);
  }
});

// 方式2：按路径上传文件（如果目录不存在会自动创建）
const result2 = await sdk.uploadToDirectoryByPath({
  depot: 'test',
  file: fileObject,
  remoteDirPath: 'web_sdk_test/upload_test', // 远程目录路径
  onProgress: (completed, total) => {
    console.log(`上传进度: ${(completed / total * 100).toFixed(1)}%`);
  }
});

// 获取下载链接
const downloadUrl = await sdk.getDownloadUrl('test', 123456);

登录和获取 Token

SDK 支持两种方式获取 token：

方式1：使用 SDK 内置登录功能（推荐）

SDK 集成了登录功能，可以直接使用：

import ArtHubWebSDK from 'arthub-web-sdk';
import { getConfigByName } from 'arthub-web-sdk';

const sdk = new ArtHubWebSDK({
  serviceConfig: getConfigByName('oa_test'),
});

// 使用 service_ticket 登录
const result = await sdk.login(serviceTicket, '11000');
// result.arthub_token 就是 token，SDK 会自动保存

方式2：使用登录组件

你也可以使用 arthubloginjssdk 进行登录，然后手动设置 token：

import arthubLoginSdk from 'arthubloginjssdk';
import ArtHubWebSDK from 'arthub-web-sdk';
import { getConfigByName } from 'arthub-web-sdk';

const loginSDK = arthubLoginSdk({
  // 配置登录选项
});

// 登录成功后获取 token
loginSDK.onLoginSuccess((token, userInfo) => {
  // 使用 token 初始化 ArtHub Web SDK
  const sdk = new ArtHubWebSDK({
    serviceConfig: getConfigByName('oa_test'),
    token: token,
  });
});

更多登录相关说明请参考 example/ARTHUB_CLIENT.md。

开发

构建 SDK

npm run build

构建产物会输出到 dist 目录。

运行示例和调试页面

重要：首次运行前需要先安装依赖

# 方式1：从主项目目录运行（会自动安装依赖）
npm run example:dev

# 方式2：手动进入 example 目录安装依赖并启动
cd example
npm install  # 首次运行必须执行，安装依赖
npm start

注意：

• npm run example:dev 会自动执行 cd example && npm install && npm start，首次运行会自动安装依赖
• 如果依赖已安装，后续可以直接运行 npm start（在 example 目录下）

配置 Host

在开发调试时，需要在 SwitchHost 或系统 hosts 文件中配置：

127.0.0.1 bag.timi.woa.com

然后访问：http://bag.timi.woa.com/test.html

如果遇到 arthubloginjssdk 导入错误：

如果页面报错无法找到 arthubloginjssdk，可以：

1. 使用"手动输入 Token"功能进行测试（推荐，无需登录组件）
2. 或构建登录组件：cd example/node_modules/arthubloginjssdk && npm run build

发布到 NPM

1. 注册 NPM 账号

如果还没有 NPM 账号，访问 npmjs.com 注册。

2. 登录 NPM

npm login

输入你的用户名、密码和邮箱。

3. 更新版本号

在 package.json 中更新版本号：

{
  "version": "0.0.2" // 例如从 0.0.1 升级到 0.0.2
}

4. 构建项目

npm run build

5. 发布

npm publish

发布前会自动执行 prepublishOnly 脚本进行构建。

6. 验证发布

访问 https://www.npmjs.com/package/arthub-web-sdk 查看你的包。

项目结构

arthub_web_sdk/
├── src/              # 源代码目录
│   └── index.ts      # SDK 入口文件
├── dist/             # 构建输出目录（发布到 npm）
├── example/          # 示例和调试页面
│   ├── index.html    # 调试页面 HTML
│   ├── index.js      # 调试页面入口
│   └── webpack.config.js  # 示例项目的 webpack 配置
├── package.json      # 主项目配置
└── tsconfig.json     # TypeScript 配置

API 文档

ArtHubWebSDK

构造函数

new ArtHubWebSDK(options: {
  serviceConfig: ServiceConfig;  // 必填：服务配置（使用 getConfigByName 获取）
  token?: string;                 // 可选：登录 token（也可以通过 login 方法设置）
  serviceId?: string;             // 可选：服务 ID（默认 '11000'）
  enableTokenCache?: boolean;      // 可选：启用 token 缓存（默认 true）
  onAuthExpired?: () => void;     // 可选：鉴权过期回调
})

预定义配置

SDK 提供了以下预定义配置，使用 getConfigByName 获取：

• 'oa' - OA 正式环境
• 'qq' - QQ 正式环境
• 'oa_test' - OA 测试环境
• 'qq_test' - QQ 测试环境
• 'public' - 公网环境

import { getConfigByName } from 'arthub-web-sdk';

const config = getConfigByName('oa_test');

uploadFile

按节点ID上传文件到 ArtHub。

sdk.uploadFile(options: {
  depot: string;                    // 必填：库名
  file: File;                       // 必填：文件对象
  parentNodeId?: number;            // 可选：父节点 ID（不提供则上传到根目录）
  sameNameOverride?: boolean;       // 可选：同名文件是否覆盖（默认 false）
  needConvert?: boolean;            // 可选：是否需要转换（默认 true）
  tagsToCreate?: string[];           // 可选：要创建的标签数组
  description?: string;              // 可选：文件描述
  onProgress?: (completed: number, total: number) => void;  // 可选：进度回调
}): Promise<NodeBrief>

uploadToDirectoryByPath

按路径上传文件到目录（如果目录不存在会自动创建）。

sdk.uploadToDirectoryByPath(options: {
  depot: string;                    // 必填：库名
  file: File;                       // 必填：文件对象
  remoteDirPath: string;            // 必填：远程目录路径（例如：'web_sdk_test/1/2'）
  sameNameOverride?: boolean;       // 可选：同名文件是否覆盖（默认 false）
  needConvert?: boolean;            // 可选：是否需要转换（默认 true）
  tagsToCreate?: string[];          // 可选：要创建的标签数组
  description?: string;             // 可选：文件描述
  onProgress?: (completed: number, total: number) => void;  // 可选：进度回调
}): Promise<NodeBrief>

说明：

• 如果指定的路径不存在，SDK 会自动创建所有必要的父目录
• 路径格式：使用 / 分隔，例如 'project_name/dir1/dir2'
• 第一个路径段会被创建为项目（project），后续路径段会被创建为目录（directory）

getDownloadUrl

获取文件的下载链接。

sdk.getDownloadUrl(depot: string, nodeId: number): Promise<string>

getNodeBrief

根据 ID 获取节点简要信息。

sdk.getNodeBrief(depot: string, ids: number[], meta?: string[]): Promise<any>

完整示例

查看 example/ 目录下的示例代码，包含：

• 登录功能演示
• 按节点ID上传文件
• 按路径上传文件
• 文件下载功能

运行示例：

npm run example:dev

更多详细的 API 文档请参考 example/API.md。

License

ISC