# @3dweb/360javascriptviewer 中文文档

规范地址：https://npmcn.com/package/%403dweb/360javascriptviewer/

版本：1\.8\.58
npm 元数据更新时间：2026-03-12T09:43:27.706Z
中文译文更新时间：2026-11-08T10:31:25.552Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%403dweb/360javascriptviewer
原文对照：https://npmcn.com/package/%403dweb/360javascriptviewer/?lang=original
项目主页：https://www.360-javascriptviewer.com/
源码仓库：https://github.com/jeroen-3dweb/360javascriptviewer

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

- 包体积（解压后）：217 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2020-07-05T21:48:34.155Z
- 最新版本发布：2026-03-12T09:43:27.585Z
- 近 30 天下载量：1799（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：163（近 12 个月 2 个）

## 中文简介

一个360个 Javascript 查看器, 与图像一起工作

## 安装

```sh
npm install @3dweb/360javascriptviewer
```

也可以使用：`pnpm add @3dweb/360javascriptviewer`、`yarn add @3dweb/360javascriptviewer`、`bun add @3dweb/360javascriptviewer`

## README

# 360 Javascript 查看器

具有缩放功能的灵活的光响应360图像取景器. 您可以使用 npm( 类型描述支持) 或者在您的页面中包含脚本。 自动化,分批装入图像,惯性和速度控制. 制作自定义进度栏,内置动画和自定义缩放功能的事件. 几种从外部导航的方法,这些方法有望使行动容易连锁. 使用来自任意位置的所有类型的图像, 并带有灵活的起始编号和文件名 .

检查示例 [360-javascriptviewer.com (中文(中国大陆) )](https://360-javascriptviewer.com/)

## 安装

使用 npm 键盘声明文件 :

```
npm i @3dweb/360javascriptviewer

import {JavascriptViewer} from "@3dweb/360javascriptviewer";
```

或使用 CDN 获取最新版本

```
<script src="https://cdn.jsdelivr.net/npm/@3dweb/360javascriptviewer@1/lib/JavascriptViewer.min.js"></script>
```

## 基本用途

首先创建用于创建360演示文稿的地盘. 我们用这个 div 的大小来计算 放大姿势 拖放和缩放事件也被添加到此 div( 默认 #jsv- holders) 中 . 在其中插入一个图像, 它往往是360 图像serie的第一个图像 。 此图像将替换为 满载时360演示文稿. 如果您不指定, 此图像将用来确定其它图像文件名 . 如果主要图像是产品. jpg,同一文件夹中的其他图像必须被称作出品 1.jpg,出品 2.jpg等. 但如果您有您360图像的其他文件名/ 位置, 您可以用 imageUrlFormat 参数更改此命名格式行为 .

```
    <script defer src="https://cdn.jsdelivr.net/npm/@3dweb/360javascriptviewer/lib/JavascriptViewer.min.js"></script>
    
    <style>
        #jsv-holder {
            width:500px;
         }
        #jsv-holder img {
            width: 100%;
         }
    </style>

    <div id="jsv-holder">
        <img id="jsv-image" alt="example" src="https://360-javascriptviewer.gumlet.io/images/phone/iphone-gold-01.png">
    </div>
    
    <script>        
        window.addEventListener('load', () => {
            const viewer = new JavascriptViewer({
                mainHolderId: 'jsv-holder', 
                mainImageId: 'jsv-image', // will hide after loading
                imageUrlFormat: 'iphone-gold-xx.png',
                totalFrames: 72,
                speed: 70,
                defaultProgressBar: true
            });
            
            // use events for example
            viewer.events().loadImage.on((progress) => {
                // use this for your own progress bar    
                console.log(`loading ${progress.percentage}%`)
            })           
             
             viewer.events().started.on((result) => {
                // use a promise or a start event to trigger things    
            })
            
             viewer.start().then(() => {
                viewer.rotateDegrees(180).then(() => {
                    // continue with your amazing intro
                })
            });
        });
    </script> 
```

# API 密码

## 构造器

| 属性 | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| 主图像Id | 字符串 | 图像的ID 是所有帧的底部 。 如果其他文件的路径不同,也可以使用主ImageUrl. | jsv-图像 |
| 主悬托 | 字符串 | 演示文稿所在的地名录 . | jsv 持有者 |
| 主图像Url | 字符串 | 第一个图像的URl,不需要在文档中. 使用图像时不需要 Urls |  |
| 总计 | 编号 | 演示文稿中的帧量,更多的图像意味着更平滑地旋转. | 72国 |
| 图像Urls | 字符串 \[\] | 图像 URLs 阵列, 覆盖全Frames 和图像 UrlFormat | \[ |
| 第一图像数 | 编号 | 装入演示文稿后, 这是第一个可见的框架 . | 1个 |
| 倒转 | 布尔 | 拖动时倒转旋转方向 . | 虚假 |
| 速度 | 编号 | 旋转速度 | 80个 |
| 惯性 | 编号 | 停止拖曳时延迟 . | 20国 |
| 默认进度栏 | 布尔 | 禁用进度栏中的构建, 当您已经执行您的加载器或不喜欢这个时使用 . | 真实 |
| 默认进度栏颜色 | 字符串 | 改变进步栏的颜色,可以是 rgb 的 ix. | rgb( 0, 0, 0) 函数 |
| 默认进度Bar背景颜色 | 字符串 | 改变进度栏的背景颜色,可以是 rgb 的 hex. | rgba(255、255、255、0.5) |
| 默认进度行高 | 字符串 | 更改进度栏的高度,可以是高度的任何 Css 值. | 5个px |
| 图像 Url 格式 | 字符串 | 用于确定框架文件名的格式 {filename} xx.{extension} 是默认的 ipod x.jpg ipod 1.jpg ipod xx.jpg ipod 01.jpg [https://other.cdn/images/ipod xx.jpg (英语)](https://other.cdn/images/ipod_xx.jpg) => [https://other.cdn/images/ipod 01.jpg (英语)](https://other.cdn/images/ipod_01.jpg) | {文件名}{xx.{扩展}} |
| 额外图像分类 | 字符串 | 在演示文稿中使用的所有图像中添加一个类,将多个类与空格分开. | 空 |
| 图像替代文本 | 字符串 | 在图像中添加一个备选文本,所有图像都会有相同的备选文本. | 空 |
| 启动Frame 否 | 编号 | 将此设置与图像 UrlFormat startFrame 合并使用 : 4-% 第一个文件是 ipod 04.jpg | 1个 |
| 自动旋转 | 编号 | 用此设置在初始时旋转视图 。 当用户拖动模型或调用其他动画方法时会停止旋转. | 0 个 |
| 自动旋转 | 编号 | 自动旋转速度 | 1个 |
| 自动旋转反转 | 布尔 | 使用此设置来改变自动旋转的方向 . | 1个 |
| 启用图像事件 | 布尔 | 使用此设置可允许在图像上点击剪接和轮盘事件 . | 0 个 |
| 缩放 | 布尔 | 启用缩放函数时使用此设置 。 放大车轮事件或捏住. | 0 个 |
| 缩放 | 编号 | 用鼠轮来改变缩放速度 . | 第50条 |
| 缩放 | 编号 | 如果启用了缩放, 这是最大缩放因子 . | 2个 |
| 站点 | 布尔 | 在到达上个图像后块块重复图像 . | 0 个 |
| 自动CDN响应器 | 布尔 | 设置查询参数的高度和宽度,以便使用图像更新器. | 0 个 |
| 自动CDNResizer 配置 | IAutoCDNResizer 配置 | 在图像 urls 中添加查询参数的配置 . | 0 个 |
| 启用变化图像事件 | 布尔 | 旋转时启用更改图像事件, 可以是 CPU 重 | 0 个 |
| 光标配置 | 课程配置 | 更改演示文稿的光标 |  |
| 连接 | 缩写 | 配置默认通知 |  |

## 方法

-   **开始( c)**: 保证  
    开始演示文稿,加载所有图像并用360演示文稿来取而代之.
-   **销毁()**: 保证  
    破坏演示文稿并返回到以前的状态..
-   **旋转Degrees( 度: 数)**: 保证  
    设定想要的旋转,360型正在旋转.
-   **旋转toDegree(目标Degree:数,最短Way?:布尔,使用Easing?布尔)**: 保证  
    旋转到一定程度。 框架nr 1为0度.
-   **旋转 ToFrame( 框架: 数字, 最短的Way? : 布尔, 使用 Easing? : 布尔)**: 保证  
    旋转到某个框架 .
-   **setSpeed( 速度: 数字)**弃权: 在图像中放大并平板.
-   **缩放( 系数: 数, x: 数, y: 数)**: 保证  
    以系数为单位并按百分比从中-1和0-1放大.
-   **set Inertia( 内地: 数量)**弃权:  
    设置查看器的当前惯性
-   **事件()**编号 :  
    使用此选项来记录事件  
    **isZoomedIn () (中文(简体) )**: 布尔 检查演示文稿是否缩放 .

## 活动

-   **装入图像**: 进展 使用此事件创建您的进度栏  
    `viewer.events().loadImage.on((progress) => { // use the progress object for your own loader })`
    
-   **开始**: 布尔 当查看器准备好时使用此事件触发其它动作  
    `viewer.events().started.on((boolean) => { // start intro animations or other creative ideas })`
    
-   **启动**: IHANLE 软件 使用此事件来抓取用户拖动 . `viewer.events().startDragging.on((handle) => { // show or hide information on the viewer or send statistics })`
    
-   **变化图**状态 : 当新图像可见时会起火, 与可启用的 ChangeImageEvent 结合工作: true `viewer.events().changeImage.on((handle) => { // show or hide information on the viewer or send statistics })`
    
-   **自动旋转**状态 : 自动旋转停止时起火 `viewer.events().endAutoRotate.on((status) => { // show or hide information on the viewer or send statistics })`
    
-   **单击**点击 当用户点击图像时开火, 与启用图像事件结合工作: 真 `viewer.events().click.on((click) => { // Use this event for zoom functions })`
    
-   **键**坐标: 当用户按住图像( 带2个指的移动区域) 时会起火, 工作结合 usualImageEvents: true `viewer.events().pinch.on((click) => { // Use this event for zoom functions })`
    
-   **滚动**: IScroll (英语) 当用户使用鼠标卷轴时会点火, 工作与启用图像Events: true `viewer.events().pinch.on((click) => { // Use this event for zoom functions })`
    
-   **双击**点击 当用户双击一幅图像时会点火, 工作与启用图像Events: true `viewer.events().pinch.on((click) => { // Use this event for zoom functions })`
    

## 接口

-   回复 {  
      当前Degree:数字;  
    {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢
    
-   IAutoCDNResizer 配置 {  
      使用 Width: 布尔; // 默认为真  
      使用H8:布尔;  
      缩放With ZoomMax:布尔; // 默认错误地加载图像, 以缩放max系数表示高度或宽度  
      外加Params: 对象; /// 在图像 urls 中添加额外参数  
    {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢
    
-   连接{  
      拖曳旋转 : {  
       显示“ 开始旋转 ”,  
       图像Url: 字符串,  
       语言: 翻译\[\],  
       主颜色:字符串 // hex, rgb 或 rgba 颜色  
       文本颜色:字符串 //hex、rgb 或 rgba 颜色  
      {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢  
    {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢
    
-   翻译 { \[  
      语言:字符串,//ISO语言代码(en-US,nl-NL)  
      文本:字符串  
    \[ \[ \]
    
-   现状{  
      当前Degree:数字;  
      当前图像:图像;   已完成:布尔; {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢
    
-   图像{  
      编号:字符串;  
      弧:字符串;   序列:编号; {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢

## 常见问题

### @3dweb/360javascriptviewer 是什么？

一个360个 Javascript 查看器, 与图像一起工作

### 如何安装 @3dweb/360javascriptviewer？

在项目目录运行 npm install @3dweb/360javascriptviewer，或使用 pnpm add / yarn add / bun add。

### @3dweb/360javascriptviewer 支持 TypeScript 吗？

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

### @3dweb/360javascriptviewer 支持 ESM 还是 CommonJS？

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

### @3dweb/360javascriptviewer 可以商用吗？

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

### @3dweb/360javascriptviewer 的下载量有多少？

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

### @3dweb/360javascriptviewer 还在维护吗？

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