Hyperlinks and Tooltips超链接和工具提示

File Format Support (click to show)

Traditional spreadsheet software, including Excel, support "Cell Links". The entire cell text is clickable.包括Excel在内的传统电子表格软件支持“单元格链接”。整个单元格文本都是可单击的。

Modern spreadsheet software, including Numbers, support "Span Links". Links are applied to text fragments within the cell content. This mirrors HTML semantics.包括数字在内的现代电子表格软件支持“跨度链接”。链接应用于单元格内容中的文本片段。这反映了HTML语义。

Formats	Link	Tooltip	Link Type
XLSX / XLSM	✔	✔	Cell Link
XLSB	✔	✔	Cell Link
XLS (BIFF8)	✔	✔	Cell Link
XLML	✔	✔	Cell Link
ODS / FODS / UOS	✔		Span Link
HTML	✔	✕	Span Link
NUMBERS	✔	✕	Span Link

X (✕) marks features that are not supported by the file formats. For example, the NUMBERS file format does not support custom tooltips.标记文件格式不支持的功能。例如，NUMBERS文件格式不支持自定义工具提示。

For "Span Link" formats, parsers apply the first hyperlink to the entire cell and writers apply the hyperlink to the entire cell text.对于“跨度链接”格式，解析器将第一个超链接应用到整个单元格，编写器将超链接应用于整个单元格文本。

Hyperlinks are stored in the l key of cell objects. 超链接存储在单元格对象的l键中。The Target field of the hyperlink object is the target of the link, including the URI fragment. Tooltips are stored in the Tooltip field and are displayed when hovering over the text.超链接对象的Target字段是链接的目标，包括URI片段。工具提示存储在Tooltip字段中，并在悬停在文本上时显示。

For example, the following snippet creates a link from cell A1 to https://sheetjs.com with the tip "Find us @ SheetJS.com!":例如，以下代码片段创建了一个从单元格A1到https://sheetjs.com的链接，并提示"Find us @ SheetJS.com!"：

ws["A1"].l = { Target: "https://sheetjs.com", Tooltip: "Find us @ SheetJS.com!" };

Following traditional software, hyperlinks are applied to entire cell objects. Some formats (including HTML) attach links to text spans. The parsers apply the first link to the entire cell. Writers apply links to the entire cell text.按照传统的软件，超链接应用于整个单元格对象。某些格式（包括HTML）将链接附加到文本跨度。解析器将第一个链接应用于整个单元格。编写器将链接应用于整个单元格文本。

Excel does not automatically style hyperlinks. They will be displayed using the default cell style.Excel不会自动设置超链接的样式。它们将使用默认的单元格样式显示。

SheetJS Pro Basic includes support for general hyperlink styling.包括对常规超链接样式的支持。

Live Example (click to hide)

Result

Loading...

Live Editor

/* The live editor requires this function wrapper */ function ExportSimpleLink(props) { return ( <button onClick={() => { /* Create worksheet */ var ws = XLSX.utils.aoa_to_sheet([ [ "Link", "No Link" ] ]); /* Add link */ ws["A1"].l = { Target: "https://sheetjs.com", Tooltip: "Find us @ SheetJS.com!" }; /* Export to file (start a download) */ var wb = XLSX.utils.book_new(); XLSX.utils.book_append_sheet(wb, ws, "Sheet1"); XLSX.writeFile(wb, "SheetJSSimpleLink.xlsx"); }}><b>Export XLSX!</b></button> ); }

/* The live editor requires this function wrapper实时编辑器需要此函数包装器 */
function ExportSimpleLink(props) { return ( <button onClick={() => {
  /* Create worksheet创建工作表 */
  var ws = XLSX.utils.aoa_to_sheet([ [ "Link", "No Link" ] ]);
  /* Add link */
  ws["A1"].l = {
    Target: "https://sheetjs.com",
    Tooltip: "Find us @ SheetJS.com!"
  };

  /* Export to file (start a download)导出到文件（开始下载） */
  var wb = XLSX.utils.book_new();
  XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
  XLSX.writeFile(wb, "SheetJSSimpleLink.xlsx");
}}><b>Export XLSX!</b></button> ); }
 

Extract all links from a file (click to show)

The following example iterates through each worksheet and each cell to find all links. The table shows sheet name, cell address, and target for each link.以下示例遍历每个工作表和每个单元格以查找所有链接。该表显示了每个链接的工作表名称、单元格地址和目标。

Result

Loading...

Live Editor

function SheetJSParseLinks(props) { const [rows, setRows] = React.useState([]); return ( <> <input type="file" onChange={async(e) => { let rows = []; /* parse workbook */ const file = e.target.files[0]; const data = await file.arrayBuffer(); const wb = XLSX.read(data); const html = []; wb.SheetNames.forEach(n => { var ws = wb.Sheets[n]; if(!ws) return; var ref = XLSX.utils.decode_range(ws["!ref"]); for(var R = 0; R <= ref.e.r; ++R) for(var C = 0; C <= ref.e.c; ++C) { var addr = XLSX.utils.encode_cell({r:R,c:C}); if(!ws[addr] || !ws[addr].l) continue; var link = ws[addr].l; rows.push({ws:n, addr, Target: link.Target}); } }); setRows(rows); }}/> <table><tr><th>Sheet</th><th>Address</th><th>Link Target</th></tr> {rows.map(r => (<tr><td>{r.ws}</td><td>{r.addr}</td><td>{r.Target}</td></tr>))} </table> </> ); }

function SheetJSParseLinks(props) {
  const [rows, setRows] = React.useState([]);

  return ( <>
    <input type="file" onChange={async(e) => {
      let rows = [];
      /* parse workbook */
      const file = e.target.files[0];
      const data = await file.arrayBuffer();
      const wb = XLSX.read(data);

      const html = [];
      wb.SheetNames.forEach(n => {
        var ws = wb.Sheets[n]; if(!ws) return;
        var ref = XLSX.utils.decode_range(ws["!ref"]);
        for(var R = 0; R <= ref.e.r; ++R) for(var C = 0; C <= ref.e.c; ++C) {
          var addr = XLSX.utils.encode_cell({r:R,c:C});
          if(!ws[addr] || !ws[addr].l) continue;
          var link = ws[addr].l;
          rows.push({ws:n, addr, Target: link.Target});
        }
      });
      setRows(rows);
    }}/>
    <table><tr><th>Sheet</th><th>Address</th><th>Link Target</th></tr>
    {rows.map(r => (<tr><td>{r.ws}</td><td>{r.addr}</td><td>{r.Target}</td></tr>))}
    </table>
  </> );
}
 

Remote Links远程链接

HTTP and HTTPS links can be used directly:HTTP和HTTPS链接可以直接使用：

ws["A2"].l = { Target: "https://docs.sheetjs.com/docs/csf/features/hyperlinks" };
ws["A3"].l = { Target: "http://localhost:7262/yes_localhost_works" };

Excel also supports mailto email links with subject line:Excel还支持mailto电子邮件链接，带有主题行：

ws["A4"].l = { Target: "mailto:[email protected]" };
ws["A5"].l = { Target: "mailto:[email protected]?subject=Test Subject" };

Live Example (click to show)

This demo creates a XLSX spreadsheet with a mailto email link. The email address input in the form never leaves your machine.此演示创建了一个带有mailto电子邮件链接的XLSX电子表格。表单中输入的电子邮件地址永远不会离开您的机器。

Result

Loading...

Live Editor

/* The live editor requires this function wrapper */ function ExportRemoteLink(props) { const [email, setEmail] = React.useState("ignored@dev.null"); const set_email = React.useCallback((evt) => setEmail(evt.target.value)); /* Callback invoked when the button is clicked */ const xport = React.useCallback(() => { /* Create worksheet */ var ws = XLSX.utils.aoa_to_sheet([ [ "HTTPS", "mailto" ] ]); /* Add links */ ws["A1"].l = { Target: "https://sheetjs.com" }; ws["B1"].l = { Target: `mailto:${email}` }; /* Export to file (start a download) */ var wb = XLSX.utils.book_new(); XLSX.utils.book_append_sheet(wb, ws, "Sheet1"); XLSX.writeFile(wb, "SheetJSRemoteLink.xlsx"); }); return ( <> <b>Email: </b><input type="text" value={email} onChange={set_email} size="50"/> <br/><button onClick={xport}><b>Export XLSX!</b></button> </> ); }

/* The live editor requires this function wrapper实时编辑器需要此函数包装器 */
function ExportRemoteLink(props) {
  const [email, setEmail] = React.useState("[email protected]");
  const set_email = React.useCallback((evt) => setEmail(evt.target.value));

  /* Callback invoked when the button is clicked单击按钮时调用的回调 */
  const xport = React.useCallback(() => {
    /* Create worksheet创建工作表 */
    var ws = XLSX.utils.aoa_to_sheet([ [ "HTTPS", "mailto" ] ]);
    /* Add links添加链接 */
    ws["A1"].l = { Target: "https://sheetjs.com" };
    ws["B1"].l = { Target: `mailto:${email}` };

    /* Export to file (start a download)导出到文件（开始下载） */
    var wb = XLSX.utils.book_new();
    XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
    XLSX.writeFile(wb, "SheetJSRemoteLink.xlsx");
  });

  return ( <>
    <b>Email: </b><input type="text" value={email} onChange={set_email} size="50"/>
    <br/><button onClick={xport}><b>Export XLSX!</b></button>
  </> );
}
 

Local Links本地链接

Links to absolute paths should use the file:// URI scheme:指向绝对路径的链接应使用file://URI方案：

ws["B1"].l = { Target: "file:///SheetJS/t.xlsx" }; /* Link to /SheetJS/t.xlsx */
ws["B2"].l = { Target: "file:///c:/SheetJS.xlsx" }; /* Link to c:\SheetJS.xlsx */

Links to relative paths can be specified without a scheme:可以在没有方案的情况下指定到相对路径的链接：

ws["B3"].l = { Target: "SheetJS.xlsb" }; /* Link to SheetJS.xlsb */
ws["B4"].l = { Target: "../SheetJS.xlsm" }; /* Link to ../SheetJS.xlsm */

Relative Paths have undefined behavior in the SpreadsheetML 2003 format. Excel 2019 will treat a ..\ parent mark as two levels up.在SpreadsheetML 2003格式中，相对路径具有未定义的行为。Excel 2019将处理..\父标记为向上两级。

Internal Links内部链接

Links where the target is a cell or range or defined name in the same workbook ("Internal Links") are marked with a leading hash character:目标是同一工作簿中的单元格、区域或定义名称的链接（“内部链接”）用前导哈希字符标记：

ws["C1"].l = { Target: "#E2" }; /* Link to cell E2 */
ws["C2"].l = { Target: "#Sheet2!E2" }; /* Link to cell E2 in sheet Sheet2 */
ws["C3"].l = { Target: "#SheetJSDName" }; /* Link to Defined Name */

Live Example (click to show)

This demo creates a workbook with two worksheets. In the first worksheet:此演示创建了一个包含两个工作表的工作簿。在第一个工作表中：

• Cell A1 ("Same") will link to the range B2:D4 in the first sheet单元格A1（“相同”）将链接到第一个工作表中的范围B2:D4
• Cell B1 ("Cross") will link to the range B2:D4 in the second sheet单元格B1（“十字”）将链接到第二个工作表中的范围B2:D4
• Cell C1 ("Name") will link to the range in the defined name SheetJSDN单元格C1（“名称”）将链接到定义名称SheetJSDN中的范围

The defined name SheetJSDN points to the range A1:B2 in the second sheet.定义的名称SheetJSDN指向第二张图纸中的范围A1:B2。

Result

Loading...

Live Editor

/* The live editor requires this function wrapper */ function ExportInternalLink(props) { return ( <button onClick={() => { /* Create empty workbook */ var wb = XLSX.utils.book_new(); /* Create worksheet */ var ws = XLSX.utils.aoa_to_sheet([ [ "Same", "Cross", "Name" ] ]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1"); /* Create links */ ws["A1"].l = { Target: "#B2:D4", Tooltip: "Same-Sheet" }; ws["B1"].l = { Target: "#Sheet2!B2:D4", Tooltip: "Cross-Sheet" }; ws["C1"].l = { Target: "#SheetJSDN", Tooltip: "Defined Name" }; /* Create stub Sheet2 */ var ws2 = XLSX.utils.aoa_to_sheet([["This is Sheet2"]]); XLSX.utils.book_append_sheet(wb, ws2, "Sheet2"); /* Create defined name */ wb.Workbook = { Names: [{Name: "SheetJSDN", Ref:"Sheet2!A1:B2"}] } /* Export to file (start a download) */ XLSX.writeFile(wb, "SheetJSInternalLink.xlsx"); }}><b>Export XLSX!</b></button> ); }

/* The live editor requires this function wrapper实时编辑器需要此函数包装器 */
function ExportInternalLink(props) { return ( <button onClick={() => {
  /* Create empty workbook创建空工作簿 */
  var wb = XLSX.utils.book_new();

  /* Create worksheet创建工作表 */
  var ws = XLSX.utils.aoa_to_sheet([ [ "Same", "Cross", "Name" ] ]);
  XLSX.utils.book_append_sheet(wb, ws, "Sheet1");

  /* Create links创建链接 */
  ws["A1"].l = { Target: "#B2:D4", Tooltip: "Same-Sheet" };
  ws["B1"].l = { Target: "#Sheet2!B2:D4", Tooltip: "Cross-Sheet" };
  ws["C1"].l = { Target: "#SheetJSDN", Tooltip: "Defined Name" };

  /* Create stub Sheet2创建存根表2 */
  var ws2 = XLSX.utils.aoa_to_sheet([["This is Sheet2"]]);
  XLSX.utils.book_append_sheet(wb, ws2, "Sheet2");

  /* Create defined name创建定义的名称 */
  wb.Workbook = {
    Names: [{Name: "SheetJSDN", Ref:"Sheet2!A1:B2"}]
  }

  /* Export to file (start a download)导出到文件（开始下载） */
  XLSX.writeFile(wb, "SheetJSInternalLink.xlsx");
}}><b>Export XLSX!</b></button> ); }
 

Some third-party tools like Google Sheets do not correctly parse hyperlinks in XLSX documents. A workaround was added in library version 0.18.12.一些第三方工具（如Google Sheets）无法正确解析XLSX文档中的超链接。在库版本0.18.12中添加了一个变通方法。

Tooltips工具提示

Tooltips are attached to hyperlink information. There is no way to specify a tooltip without assigning a cell link.工具提示附加到超链接信息。如果不指定单元链接，就无法指定工具提示。

Excel has an undocumented tooltip length limit of 255 characters.Excel的未记录工具提示长度限制为255个字符。

Writing longer tooltips is currently permitted by the library but the generated files will not open in Excel.库当前允许编写更长的工具提示，但生成的文件不会在Excel中打开。

HTML

The HTML DOM parser¹ will process <a> links in the table.HTML DOM解析器¹将处理表中的<a>链接。

Live Example (click to hide)

This example uses table_to_book to generate a SheetJS workbook object from a HTML table. The hyperlink in the second row will be parsed as a cell-level link.此示例使用table_to_book从HTML表生成SheetJS工作簿对象。第二行中的超链接将被解析为单元格级链接。

Result

Loading...

Live Editor

/* The live editor requires this function wrapper */ function ExportHyperlink(props) { /* Callback invoked when the button is clicked */ const xport = React.useCallback(() => { /* Create worksheet from HTML DOM TABLE */ const table = document.getElementById("TableLink"); const wb = XLSX.utils.table_to_book(table); /* Export to file (start a download) */ XLSX.writeFile(wb, "SheetJSHTMLHyperlink.xlsx"); }); return ( <> <button onClick={xport}><b>Export XLSX!</b></button> <table id="TableLink"><tbody><tr><td> Do not click here, for it is link-less. </td></tr><tr><td> <a href="https://sheetjs.com">Click here for more info</a> </td></tr></tbody></table> </> ); }

/* The live editor requires this function wrapper实时编辑器需要此函数包装器 */
function ExportHyperlink(props) {

  /* Callback invoked when the button is clicked单击按钮时调用的回调 */
  const xport = React.useCallback(() => {
    /* Create worksheet from HTML DOM TABLE从HTML DOM TABLE创建工作表 */
    const table = document.getElementById("TableLink");
    const wb = XLSX.utils.table_to_book(table);

    /* Export to file (start a download)导出到文件（开始下载） */
    XLSX.writeFile(wb, "SheetJSHTMLHyperlink.xlsx");
  });

  return ( <>
    <button onClick={xport}><b>Export XLSX!</b></button>
    <table id="TableLink"><tbody><tr><td>
      Do not click here, for it is link-less.不要点击这里，因为它是无链接的。
    </td></tr><tr><td>
      <a href="https://sheetjs.com">Click here for more info</a>
    </td></tr></tbody></table>
  </> );
}
 

The HTML writerHTML编写器² will generate <a> links.将生成<a>链接。

Live Example (click to hide)

This example creates a worksheet where A1 has a link and B1 does not. 此示例创建一个工作表，其中A1有链接，而B1没有。The sheet_to_html function generates an HTML table where the topleft table cell has a standard HTML link.sheet_to_html函数生成一个html表，其中左上方的表单元格有一个标准的html链接。

Result

Loading...

Live Editor

/* The live editor requires this function wrapper */ function ExportALinks(props) { const [ __html, setHTML ] = React.useState(""); React.useEffect(() => { /* Create worksheet */ var ws = XLSX.utils.aoa_to_sheet([ [ "Link", "No Link" ] ]); /* Add link */ ws["A1"].l = { Target: "https://sheetjs.com", Tooltip: "Find us @ SheetJS.com!" }; /* Generate HTML */ setHTML(XLSX.utils.sheet_to_html(ws)); }, []); return ( <div dangerouslySetInnerHTML={{__html}}/> ); }

/* The live editor requires this function wrapper实时编辑器需要此函数包装器 */
function ExportALinks(props) {
  const [ __html, setHTML ] = React.useState("");
  React.useEffect(() => {
    /* Create worksheet */
    var ws = XLSX.utils.aoa_to_sheet([ [ "Link", "No Link" ] ]);
    /* Add link */
    ws["A1"].l = {
      Target: "https://sheetjs.com",
      Tooltip: "Find us @ SheetJS.com!"
    };

    /* Generate HTML */
    setHTML(XLSX.utils.sheet_to_html(ws));
  }, []);

  return ( <div dangerouslySetInnerHTML={{__html}}/> );
}
 

---

1. The primary SheetJS DOM parsing methods are table_to_book, table_to_sheet, and sheet_add_dom主要的SheetJS DOM解析方法是table_to_book、table_to_sheet和sheet_add_dom↩
2. HTML strings can be written using bookType: "html" in the write or writeFile methods or by using the dedicated sheet_to_html utility functionHTML字符串可以使用write或writeFile方法中的bookType: "html"编写，也可以使用专用的sheet_to_html实用程序函数编写↩