> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# excelGet

> 按工作表名稱從 Excel 工作簿中取得值，支援特定單元格引用和帶可選輸出對映的單元格範圍查詢。

從 Excel 工作簿中取得值。 當 **翻譯模式** 設定為 **範本** 時，此操作通常在 [Excel 端口](../../connectors/excel) 的範本檔案中使用。 不過，此操作也可以用於專用指令碼場景，例如[Script 端口](../../connectors/script)。

## 必需的參數

* **sheet**: 工作簿中要從中檢索值的工作表。

## 可選的參數

* **version**：目標工作簿的 Excel 版本。 允許的值為`AUTO`、`95`、`97-2003`、`2007`。 預設為 `AUTO`。
* **file**：Excel 工作簿在磁碟上的完整路徑，包括檔名。 必須指定`file`或`handle`參數。
* **handle**：對[excelOpen](./op-excel-open)建立的Excel資料的可讀控制代碼引用。 如果指定`file`參數，則不需要`handle`。
* **map:\***：一組一個或多個輸入，其中對映參數的名稱位於冒號之前（例如，`map:foo`），值是工作表中單元格的名稱或範圍。 例如，值為`C1`的屬性`map:foo`在操作的指定輸出項上建立`foo`屬性，其值是在目標工作表的單元格 C1 中找到的值。

  還可以指定一個單元格範圍以檢索該範圍內所有單元格的值。 例如，`C1:C10` 檢索單元格 C1 到 C10 的所有值。 可以使用萬用字元`*`來取得列長度的單元格值。 例如，`C1:C*`檢索從 C1 到列末尾的所有值。

## 輸出屬性

* **\***: 取決於工作表的內容和指定的查詢。 如果存在列標題，則它們用於命名輸出屬性。 此外，如果在輸入項上設定`map:*`參數，則輸出項包含具有相同名稱的屬性。 有關其他上下文，請參閱[範例](#範例)。

## 範例

有關其他資訊和更多範例，請參閱 [Excel 端口](../../connectors/excel) 文件的 [Excel 到 XML](../../connectors/excel#excel-to-xml) 部分。

### 取得值並對映到新物件

此範例使用 excelGet 操作從指定工作表中的單元格和列中取得特定的範圍值，並將它們對映到新專案。 稍後可以在範本中使用新專案來填充 XML 輸出檔案的特定 XML 元素，作為 Excel 端口範本模式的一部分。 有關 `arc:call` 中使用的 `arc:map` 關鍵字的詳細資訊，請參閱 [arc:map](../keyword-reference/op-arc-map)。

```xml theme={null}
<!-- Read the Excel -->
<arc:set attr="excel.file" value="[FilePath]" />
<arc:set attr="excel.sheet" value="Sheet1" />
<arc:set attr="excel.version" value="2007" />

<!-- Map the specific and ranged values to various attributes -->
<arc:setm item="excel">
  map:PONumber = "C5"
  map:PODate = "C6"
  map:DeliveryDate = "C7"
  map:ShipDate = "C8"
  map:BillerName = "I11"
  map:ShipperName = "C11"
  map:ShipperAddressLine1 = "C12"
  map:ShipperCity = "C13"
  map:ShipperState = "C14"
  map:ShipperZip = "C15"
  map:LineUPC = "B19:B*"
  map:LineQty = "C19:C*"
  map:LineUnit = "D19:D*"
  map:LinePrice = "E19:E*"
  map:LineDesc = "F19:F*"
  map:LineAllowanceRate = "I19:I*"
  map:LineAllowanceType = "J19:J*"
</arc:setm>

<!-- Calling the excelGet operation and using the arc:map keyword to map the output of the operation from the "result" item to a new "data" item that can be used later -->
<arc:call op="excelGet" in="excel" out="result">
  <arc:map from="result" to="data" map="*=*" />
</arc:call>
```

### 在 Script 端口中使用 excelGet

此範例使用 [Script 端口](../../connectors/script) 中的 excelGet 操作開啟磁碟上現有的 Excel 工作簿並從特定單元格讀取資料。 然後關閉 Excel 工作簿，指令碼將該資料作為新的輸出檔案推送。

```xml theme={null}
<!-- Creating the input item for the operation and passing it in -->
<arc:set attr="excel.file" value="C:\Temp\movies.xlsx" />
<arc:call op="excelOpen" in="excel" out="result" >
  <!-- Resolving the handle from excelOpen to use in excelGet -->
  <arc:set attr="get.handle" value="[result.handle]" />
  <arc:set attr="get.sheet" value="film" />
  <arc:set attr="get.version" value="2007" />
  <arc:set attr="get.map:favoritemovie" value="A2" />
  <arc:set attr="get.map:favoritemovieyear" value="B2" />
  <!-- Calling excelGet inside excelOpen to use the handle -->
  <arc:call op="excelGet" in="get" out="out">
    <!-- Creating some output data and file from the data read from the excel sheet -->
    <arc:set attr="output.data" value="My favorite movie is [out.favoritemovie] and it came out in [out.favoritemovieyear]." />
    <arc:set attr="output.filename" value="results.txt" />
    <!-- Using the arc:finally keyword to execute the closing of the handle last -->
    <arc:finally>
      <!-- Calling excelClose to close the handle -->
      <arc:call op="excelClose" in="excel" out="close">
        <!-- Check to ensure the handle was closed and throw an error if it was not -->
        <arc:exists attr="close.success" >
          <arc:else>
            <arc:throw code="CloseFailed" desc="The handle was not closed successfully." />
          </arc:else>
        </arc:exists>
      </arc:call>
    </arc:finally>
  </arc:call>
</arc:call>
<!-- Push the output item out as a file -->
<arc:push item="output" />
```