概述
本 Demo 展示了如何创建和配置名称框（NameBox）组件。名称框是一个类似 Excel 的交互式组件，能够显示当前选中的单元格范围或命名范围，支持用户快速导航到指定的命名范围或绘图项（如图表、切片器）。Demo 中演示了名称框的基本用法以及如何通过选项控制其行为。
实现思路
创建 Spread 实例，并初始化两个工作表
创建 NameBox 实例，绑定到 Spread 实例和 DOM 容器
初始化示例数据：添加表格、切片器和图表
添加多个自定义名称（包括工作簿级别和工作表级别）
绑定事件监听器，通过选项动态控制名称框的行为
代码解析
创建名称框实例
这段代码创建了 NameBox 实例。构造函数接收三个参数：宿主元素（可以是 DOM 元素或元素 ID）、Spread 实例、以及可选的配置选项对象。创建后，名称框会自动响应 UI 行为更新显示内容。
添加自定义名称
通过 addCustomName 方法添加自定义名称。工作簿级别的名称可以在所有工作表中使用，工作表级别的名称仅在当前工作表中有效。参数依次为：名称、公式或范围引用、基准行、基准列、备注（可选）、是否只读（可选）。
动态配置选项
通过修改 nameBox.options 对象的属性，可以动态控制名称框的行为。enableAddCustomName 控制是否允许添加自定义名称，enableNavigateToRange 控制是否允许导航到范围，showCustomNameList 控制是否显示下拉列表，dropDownMaxHeight 控制下拉列表的最大高度。
运行效果
名称框实时显示当前选中的单元格范围（如 A1、B2:D5）
点击名称框下拉箭头，可以查看所有自定义名称的列表
在名称框中输入命名范围名称并按回车，可以快速导航到该范围
在名称框中输入图表名称（如 chart1），可以选中该图表
在名称框中输入切片器名称（如 salesman），可以选中该切片器
勾选或取消勾选右侧的复选框，可以实时调整名称框的行为
修改下拉框最大高度输入框的值，可以调整下拉列表的最大高度
API 参考
NameBox 构造函数
host：DOM 元素或元素 ID，名称框的容器
workbook：Spread 实例
options：可选的配置对象，类型为 INameBoxOptions
INameBoxOptions 接口
dropDownMaxHeight：下拉列表元素的最大高度（像素），默认值为 500
enableAddCustomName：是否允许在输入不存在的名称时添加到选择器中，默认值为 true
enableNavigateToRange：是否允许在输入名称或点击列表项时导航到命名范围或绘图项，默认值为 true
showCustomNameList：是否显示自定义名称列表下拉指示器，默认值为 true
refresh 方法
手动刷新名称框，将名称框的值同步到工作表选择。当通过代码设置选择范围时（不会触发 selectionChanged 事件），需要手动调用此方法。
addCustomName 方法
name：自定义名称
formula：公式或范围引用
baseRow、baseCol：基准行和基准列
comment：可选的备注
isReadOnly：可选，是否只读
window.onload = function () {
var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"), {sheetCount: 2});
initSpread(spread);
var nameBox = new GC.Spread.Sheets.NameBox.NameBox('nameBox', spread);
bindEvents(spread, nameBox);
};
function changeProperty(nameBox, pn, value) {
nameBox.options[pn] = value;
}
function bindEvents(spread, nameBox) {
["enableAddCustomName", "enableNavigateToRange", "showCustomNameList"].forEach(function (pn) {
document.getElementById(pn).addEventListener("change", function (e) {
changeProperty(nameBox, pn, !! e.target.checked);
});
});
document.getElementById("dropDownMaxHeight").addEventListener("change", function (e) {
let value = + e.target.value;
nameBox.options.dropDownMaxHeight = value;
});
}
function initSpread(spread) {
var sheet = spread.getSheet(0);
initTable(spread);
initSlicer(sheet);
initChart(sheet);
spread.addCustomName("workBookName1", "Sheet1!A2:D4", 0, 0, "");
spread.addCustomName("workBookName2", "Sheet2!B3:E6", 0, 0, "");
sheet.addCustomName("sheet1Name1", "C2:D3", 0, 0, "");
sheet.addCustomName("sheet1Name2", "B4:E10", 0, 0, "");
spread.getSheet(1).addCustomName('sheet2Name1', "D4:G6", 0, 0, "");
}
function initTable(spread) {
var dataSource = [
[
"salesman",
"product",
"date",
"amount",
"price",
"sales"
],
[
"Colleen Lee",
"desk",
new Date("2020-10-08T16:00:00.000Z"),
5,
199,
995
],
[
"Joe Mercer",
"pen",
new Date("2020-09-15T16:00:00.000Z"),
2,
5,
10
],
[
"Alicia Schmidt",
"pencil",
new Date("2021-06-22T16:00:00.000Z"),
6,
1.5,
9
],
[
"John Walsh",
"chair",
new Date("2021-07-19T16:00:00.000Z"),
7,
68,
476
],
[
"David Hale",
"notebook",
new Date("2021-01-13T16:00:00.000Z"),
7,
3.2,
22.4
],
[
"Gordon Jones",
"desk",
new Date("2021-03-12T16:00:00.000Z"),
9,
199,
1791
],
[
"Colleen Lee",
"pen",
new Date("2021-03-06T16:00:00.000Z"),
4,
5,
20
],
[
"Colleen Lee",
"pencil",
new Date("2020-09-02T16:00:00.000Z"),
10,
1.5,
15
],
[
"Joe Mercer",
"chair",
new Date("2020-08-09T16:00:00.000Z"),
3,
68,
204
],
[
"Alicia Schmidt",
"notebook",
new Date("2021-02-08T16:00:00.000Z"),
9,
3.2,
28.8
],
[
"John Walsh",
"desk",
new Date("2021-07-03T16:00:00.000Z"),
7,
199,
1393
],
[
"David Hale",
"pen",
new Date("2021-06-27T16:00:00.000Z"),
8,
5,
40
],
[
"Gordon Jones",
"pencil",
new Date("2020-10-10T16:00:00.000Z"),
2,
1.5,
3
],
[
"Colleen Lee",
"chair",
new Date("2021-03-04T16:00:00.000Z"),
2,
68,
136
],
[
"Colleen Lee",
"notebook",
new Date("2021-02-21T16:00:00.000Z"),
11,
3.2,
35.2
],
[
"Joe Mercer",
"desk",
new Date("2021-06-03T16:00:00.000Z"),
6,
199,
1194
]
];
var sheet1 = spread.sheets[0];
sheet1.setArray(0, 0, dataSource);
var table = sheet1.tables.add("table1", 0, 0, 17, 6, GC.Spread.Sheets.Tables.TableThemes.light9);
var sheet2 = spread.sheets[1];
sheet2.setArray(0, 0, dataSource);
var table2 = sheet2.tables.add("table2", 0, 0, 17, 6, GC.Spread.Sheets.Tables.TableThemes.light9);
//setColumnWidth: sheet1
sheet1.setColumnWidth(0, 90);
sheet1.setColumnWidth(1, 80);
sheet1.setColumnWidth(2, 130);
sheet1.setColumnWidth(3, 70);
//setColumWidth: sheet2
sheet2.setColumnWidth(0, 90);
sheet2.setColumnWidth(1, 80);
sheet2.setColumnWidth(2, 130);
sheet2.setColumnWidth(3, 70);
}
function initSlicer(sheet) {
var slicer_name = sheet.slicers.add("salesman", "table1", "Salesman", GC.Spread.Sheets.Slicers.SlicerStyles.light3(), GC.Spread.Sheets.Slicers.SlicerType.table);
slicer_name.startRow(0);
slicer_name.startColumn(7);
slicer_name.startColumnOffset(0);
}
function initChart(sheet) {
var chart = sheet.charts.add("chart1", GC.Spread.Sheets.Charts.ChartType.line, 100, 400, 400, 300, 'C1:D17');
}
<!doctype html>
<html style="height:100%;font-size:14px;">
<head>
<meta charset="utf-8" />
<meta name="spreadjs culture" content="zh-cn" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css"
href="$DEMOROOT$/zh/purejs/node_modules/@grapecity-software/spread-sheets/styles/gc.spread.sheets.excel2013white.css">
<script src="$DEMOROOT$/zh/purejs/node_modules/@grapecity-software/spread-sheets/dist/gc.spread.sheets.all.min.js"
type="text/javascript"></script>
<script
src="$DEMOROOT$/zh/purejs/node_modules/@grapecity-software/spread-sheets-shapes/dist/gc.spread.sheets.shapes.min.js"
type="text/javascript"></script>
<script
src="$DEMOROOT$/zh/purejs/node_modules/@grapecity-software/spread-sheets-slicers/dist/gc.spread.sheets.slicers.min.js"
type="text/javascript"></script>
<script
src="$DEMOROOT$/zh/purejs/node_modules/@grapecity-software/spread-sheets-charts/dist/gc.spread.sheets.charts.min.js"
type="text/javascript"></script>
<script
src="$DEMOROOT$/zh/purejs/node_modules/@grapecity-software/spread-sheets-resources-zh/dist/gc.spread.sheets.resources.zh.min.js"
type="text/javascript"></script>
<script src="$DEMOROOT$/spread/source/js/license.js" type="text/javascript"></script>
<script src="app.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css">
</head>
<body>
<div class="sample-tutorial">
<div class="sample-container">
<div id="ss" class="sample-spreadsheets"></div>
</div>
<div class="sample-options">
<div class="options-container">
<h3>名称框容器</h3>
<div id="nameBox"></div><br />
<h3>名称框选项</h3>
<div class="option-row">
<input type="checkbox" id="enableAddCustomName" checked />
<label for="enableAddCustomName">启用添加自定义名称</label>
</div>
<div class="option-row">
<input type="checkbox" id="enableNavigateToRange" checked />
<label for="enableNavigateToRange">启用导航到范围</label>
</div>
<div class="option-row">
<input type="checkbox" id="showCustomNameList" checked />
<label for="showCustomNameList">显示自定义名称列表</label>
</div>
<div class="option-row"><br />
下拉框最大高度:
<input type="number" id="dropDownMaxHeight" min="0" step="1" value="500" />
</div>
</div>
</div>
</div>
</body>
</html>
.sample-options {
width: 260px;
height: 100%;
}
.sample-tutorial {
position: relative;
height: 98vh;
overflow: hidden;
display: flex;
}
.sample-container {
width: calc(100% - 280px);
height: 100%;
}
.options-container {
width: 100%;
padding: 12px;
height: 100%;
box-sizing: border-box;
background: #fbfbfb;
overflow: auto;
}
.option-row {
font-size: 14px;
padding: 5px;
margin-top: 10px;
}
label {
display: block;
margin-bottom: 6px;
}
input {
padding: 4px 6px;
}
input[type=button] {
margin-top: 6px;
display: block;
}
body {
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
}
#ss {
height: 100%;
}
#nameBox {
width: 80%;
height: 25px;
}
label {
display: inline-block;
}
p {
font-size: 12px;
font-weight: bold;
}
h3 {
white-space: nowrap;
}
#dropDownMaxHeight {
width: 40px;
}
