项目参数

项目参数是全局的一个参数配置，可以在 API 数据源的 URL、BODY、HEADER 以及数据库数据源的 SQL 语句中进行关联。可以使用交互或者二开代码直接设置，也可以在内嵌山海鲸页面时通过 URL 参数透传进来。此参数可以被用在很多的场景之中，如根据不同条件进行数据筛选，项目集成时的透传参数等等。下文通过项目参数的创建，项目参数值的设置和项目参数的使用三个部分来介绍：

1.项目参数的创建

设置项目参数的位置在看板编辑界面左上角“项目”下拉菜单中点击“项目设置”弹窗中。

其中参数名称是我们在其他地方引用这个参数或者设置这个参数时会用到的名称，推荐大家以英文单词的形式命名，而参数默认值则是在当前参数未被修改的情况下的取值。

2.项目参数值的修改

项目参数的值可以通过三种方式进行修改：

2.1 直接修改默认值

在没有做进一步修改的情况下，项目参数将直接使用其默认值。默认值可以在项目参数的设置中直接修改，也可以在访客管理中进行分访客设置。（访客管理是山海鲸中最轻量的一个权限管理功能，具体教程可以参考访客管理的文档。有时我们不仅希望不同访客看到不同的页面，也希望不同访客在同一页面中看到不同的数据，此时我们可以给不同的访客设置不同的项目参数默认值，再将参数值带入到数据连接中即可。）

如我们全局设置了一个项目参数，项目名称叫做 city，在访客管理的设置中我们希望不同城市的访客可以看到不同的数据，那么我们针对上海的访客可以将参数默认值设置成上海：

（注意：项目参数创建后要点击保存才能同步到访客管理里的参数名称下拉框中）

是否锁定参数选项，代表该项目参数在项目运行的过程中能不能被修改。如果开启，代表不能被任何下文提到的方式进行修改。一般来说对权限敏感度高的场景中一定要勾选此选项。

2.2 通过 URL 传参覆盖参数值

很多时候，我们需要将山海鲸的项目发布成 URL 后，通过 iFrame 的方式集成到其他网页当中。这个时候，可以通过 URL 的参数传递的方式修改项目参数。

同样如 2.1 中设置的 city 参数而言，当我们把当前项目发布成链接之后，得到发布链接为

http://192.168.31.136:1025/hnyxjkvwiz5g/

那么我们可以通过在连接后增加参数的形式来传递，如

http://192.168.31.136:1025/hnyxjkvwiz5g/?city=%E4%B8%8A%E6%B5%B7

注意 city 后的参数实际是中文上海，需要用 URLEncode 后传入（这里采用 UTF8 编码）。

这样项目内得到的项目参数 city 的值就将是”上海”，我们通过交互将一个文本组件在入场时文本内容设置成项目参数的内容，可以直观的看一下结果：

当我们直接访问不带参数的链接时（http://192.168.31.136:1025/c3nq6q0exwib/），将直接会显示项目参数的默认值：

当我们访问带参数的链接后（http://192.168.31.136:1025/hnyxjkvwiz5g/?city=%E4%B8%8A%E6%B5%B7），会显示 URL 上的 city 参数值：

2.3 通过交互修改参数值

项目参数还可以通过交互进行设置，我们这里以点击按钮修改为例来看看交互如何修改项目参数。

首先我们在看板中添加一个按钮组件，给这个按钮组件添加一个点击事件触发的交互：

点击后将项目参数的 city 参数设置成”杭州”。如果要同时修改多个项目参数，则在参数名称中选择多个，下面就会出现多个参数列表可以注意设置修改值。

由于在项目参数被修改后，文本内容并不会自动更新，因为文本内容设置的是入场时替换成项目参数的值，此时并不会触发这个事件。为了方便演示，我们需要添加一个交互，强制同步一下文本的内容。如下图所示：

设置完成之后保存项目，我们再次在浏览器中打开项目的发布链接，点击按钮之后可以看到：

2.4 通过二开代码修改参数

二开代码中可以通过 project 对象直接修改项目参数：

class Button {
  init() {
    // 按钮点击后修改项目参数city为成都
    this.element.addEventListener("click", (ev) => {
      this.project.setVariable("city", "成都");
    });
  }
}
export default Button;

3 项目参数的使用

项目参数可以在项目中很多地方使用，使用的方式一般都是填入这样的格式：**{:参数名称}**

比如当参数名称是 city 的时候，则使用的地方写入“{:city}”，在运行时就会被自动替换成 city 参数的值。

目前项目中一共可以在以下五种地方使用项目参数：

3.1 动态连接 API 数据

我们在连接 API 数据时通常会有这样的需求，比如筛选不同地区的销售数据，也可能是不同的访客看到的数据不一样，这些需求都可以通过在连接 API 数据时填入项目参数的形式来实现。

在连接 API 数据时，我们可以将项目参数替换 API 的URL、BODY、HEADER中的部分内容，此处我们以 URL 为例来看一下 API 连接中如何使用项目参数。

首先，我们有一个 API 的地址，这里我们用我们的山海鲸数据管家生成一个最简单的 API：

http://192.168.31.136:65535/v1/app/4e33ed8b-1d91-4b73-ab26-cb204508c572/46fa577b/?type=%E4%B8%8A%E6%B5%B7

读取一个 type 参数，输出的 output 是”输入城市:type”的形式，如图所示

我们将这个 API 导入到山海鲸当中，注意在参数中需要填写成如下的形式：

http://192.168.31.136:65535/v1/app/4e33ed8b-1d91-4b73-ab26-cb204508c572/46fa577b/?type={:city}

点击确定后可以看到：

为了方便演示，我们还要做一些设置让数据显示出来，我们修改文本组件的文本选项生成数据字段：

并将刚刚的数据绑定到文本组件的文本数据中：

此时我们手动修改项目参数的默认值为雄安，刷新数据后可以看到：

（注意：在编辑和运行时用其他方式修改项目参数，和项目参数相关的数据会自动刷新，无需手动刷新）

我们的 API 已经读取到了新的项目参数并输出了一个新的根据这个项目参数的字符串。

3.2 数据库 SQL 语句

和 API 数据连接一样，数据库的连接很多时候也需要根据条件动态获取数据，我们这里以一张 student 表为例看一下我们如何做一个数据筛选的案例。

首先，先在全局添加一个 sex 项目参数，默认值填入男:

我们连接数据库，填入 mysql 的服务器参数，点击连接按钮后看到所有数据库和表：

选择好了数据库后，选择 SQL 模式，填入 SQL 语句：

1	select * from `student` where `sex`='{:sex}';

特别注意的是，SQL 语句中的参数只是替换，因此需要引号的地方还是需要把引号写出来。

点击确定之后，可以看到查出来了数据库中所有性别为男的数据：

我们将这个数据绑定到表格组件上：

我们加入一个下拉组件，将下拉选项改为男和女，为其添加一个选中以下选项时的交互，将选中男时将项目参数改为男：

同理设置选中女时的情况，设置完成后，由于项目参数改动成功后，数据会自动刷新，因此我们不用再做额外的设置。这样我们就可以实现一个简单的按需获取数据的方案：

3.3 交互设置组件属性

在交互中我们可以通过修改设置来设置组件的属性值，在属性值的地方可以通过动态值的自定义公式来使用项目参数，详细的设置方式和示例项目请参考这个教程 →_→ 动态值传递（交互）

3.4 交互筛选组件

在我们设置交互时，有的时候需要对交互作用到的对象进行筛选，特别是在 3D 场景中，我们经常希望只显示某一个楼层下的人员或者桌椅，此时我们就可以借助项目参数结合组件筛选来动态选择交互所作用的对象组件。

可以先看下我们这样一个模型，模型中每一层都有一个外立面和一个楼板：

我们可以设置一个项目参数来决定是显示楼板还是显示外立面：

然后添加一个按钮，并添加两个交互，第一个交互先把所有的组件都隐藏，只需要筛选词填空就代表选择所有组件，如下图所示：

然后再添加一个交互，将项目参数中关联的模型都显示出来：

我们点击之后可以看到，楼板都被隐藏，而外立面还是显示中：

3.5 二开代码中获取

二开代码中可以直接获取到项目参数的值：

class Button {
  init() {
    // 按钮点击后修改项目参数city为成都
    this.element.addEventListener("click", (ev) => {
      console.log(
        "当前的项目参数city的值是：" + this.project.getVariable("city")
      );
    });
  }
}
export default Button;