org.apache.poi.ss.usermodel

Interface Name

All Known Implementing Classes:

ExternalLinksTable.ExternalName, HSSFName, XSSFName

public interface Name

Represents a defined name for a range of cells.

A name is a meaningful shorthand that makes it easier to understand the purpose of a cell reference, constant or a formula.

Examples:

        
        

         
         
  Sheet sheet = workbook.createSheet("Loan Calculator");
  Name name;

  name = workbook.createName();
  name.setNameName("Interest_Rate");
  name.setRefersToFormula("'Loan Calculator'!$E$5");

  name = wb.createName();
  name.setNameName("Loan_Amount");
  name.setRefersToFormula("'Loan Calculator'!$E$4");

  name = wb.createName();
  name.setNameName("Number_of_Payments");
  name.setRefersToFormula("'Loan Calculator'!$E$10");

  name = wb.createName();
  name.setNameName("Monthly_Payment");
  name.setRefersToFormula("-PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)");

  name = wb.createName();
  name.setNameName("Values_Entered");
  name.setRefersToFormula("IF(Loan_Amount*Interest_Rate>0,1,0)");

 
        
        

(代表一系列单元格的定义名称。名称是一种有意义的简写，可以更容易地理解单元格引用、常量或公式的用途。示例： Sheet sheet = workbook.createSheet("Loan Calculator");姓名姓名；名称 = 工作簿.createName(); name.setNameName("Interest_Rate"); name.setRefersToFormula("'贷款计算器'!$E$5");名称 = wb.createName(); name.setNameName("Loan_Amount"); name.setRefersToFormula("'贷款计算器'!$E$4");名称 = wb.createName(); name.setNameName("Number_of_Payments"); name.setRefersToFormula("'贷款计算器'!$E$10");名称 = wb.createName(); name.setNameName("Monthly_Payment"); name.setRefersToFormula("-PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)");名称 = wb.createName(); name.setNameName("Values_Entered"); name.setRefersToFormula("IF(Loan_Amount*Interest_Rate>0,1,0)");)

Method Summary

Modifier and Type	Method and Description
java.lang.String	getComment() Returns the comment the user provided when the name was created. (返回创建名称时用户提供的评论。)
java.lang.String	getNameName() Gets the name of the named range (获取命名范围的名称)
java.lang.String	getRefersToFormula() Returns the formula that the name is defined to refer to. (返回定义名称以引用的公式。)
int	getSheetIndex() Returns the sheet index this name applies to. (返回此名称适用的工作表索引。)
java.lang.String	getSheetName() Get the sheets name which this named range is referenced to (获取此命名范围所引用的工作表名称)
boolean	isDeleted() Checks if this name points to a cell that no longer exists (检查此名称是否指向不再存在的单元格)
boolean	isFunctionName() Checks if this name is a function name (检查此名称是否为函数名称)
boolean	isHidden() Checks if this name is hidden, eg one of the built-in Excel internal names (检查此名称是否隐藏，例如内置 Excel 内部名称之一)
void	setComment(java.lang.String comment) Sets the comment the user provided when the name was created. (设置创建名称时用户提供的注释。)
void	setFunction(boolean value) Indicates that the defined name refers to a user-defined function. (表示定义的名称是指用户定义的函数。)
void	setNameName(java.lang.String name) Sets the name of the named range (设置命名范围的名称)
void	setRefersToFormula(java.lang.String formulaText) Sets the formula that the name is defined to refer to. (设置定义名称以引用的公式。)
void	setSheetIndex(int sheetId) Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook. (告诉 Excel 此名称适用于具有指定索引的工作表，而不是整个工作簿。)

Method Detail

getSheetName

java.lang.String getSheetName()

Get the sheets name which this named range is referenced to (获取此命名范围所引用的工作表名称)

Returns:

sheet name, which this named range referred to (工作表名称，此命名范围引用)

getNameName

java.lang.String getNameName()

Gets the name of the named range (获取命名范围的名称)

Returns:

named range name (命名范围名称)

setNameName

void setNameName(java.lang.String name)

Sets the name of the named range

The following is a list of syntax rules that you need to be aware of when you create and edit names.

• Valid characters The first character of a name must be a letter, an underscore character (_), or a backslash (\). Remaining characters in the name can be letters, numbers, periods, and underscore characters.
• Cell references disallowed Names cannot be the same as a cell reference, such as Z$100 or R1C1.
• Spaces are not valid Spaces are not allowed as part of a name. Use the underscore character (_) and period (.) as word separators, such as, Sales_Tax or First.Quarter.
• Name length A name can contain up to 255 characters.
• Case sensitivity Names can contain uppercase and lowercase letters.

A name must always be unique within its scope. POI prevents you from defining a name that is not unique within its scope. However you can use the same name in different scopes. Example:

            
            

             
             
 //by default names are workbook-global
 Name name;
 name = workbook.createName();
 name.setNameName("sales_08");

 name = workbook.createName();
 name.setNameName("sales_08"); //will throw an exception: "The workbook already contains this name (case-insensitive)"

 //create sheet-level name
 name = workbook.createName();
 name.setSheetIndex(0); //the scope of the name is the first sheet
 name.setNameName("sales_08");  //ok

 name = workbook.createName();
 name.setSheetIndex(0);
 name.setNameName("sales_08");  //will throw an exception: "The sheet already contains this name (case-insensitive)"

 
            
            

(设置命名范围的名称 以下是创建和编辑名称时需要注意的语法规则列表。有效字符 名称的第一个字符必须是字母、下划线字符 (_) 或反斜杠 ()。名称中的剩余字符可以是字母、数字、句点和下划线字符。不允许单元格引用 名称不能与单元格引用相同，例如 Z$100 或 R1C1。空格无效 空格不允许作为名称的一部分。使用下划线字符 (_) 和句点 (.) 作为单词分隔符，例如 Sales_Tax 或 First.Quarter。名称长度 名称最多可包含 255 个字符。区分大小写 名称可以包含大写和小写字母。名称在其范围内必须始终是唯一的。 POI 阻止您定义在其范围内不唯一的名称。但是，您可以在不同的范围内使用相同的名称。示例：//默认名称为 workbook-global Name name;名称 = 工作簿.createName(); name.setNameName("sales_08");名称 = 工作簿.createName(); name.setNameName("sales_08"); //将抛出异常：“工作簿已包含此名称（不区分大小写）” //创建工作表级名称 name = workbook.createName(); name.setSheetIndex(0); //名称的范围是第一张表 name.setNameName("sales_08"); //ok name = workbook.createName(); name.setSheetIndex(0); name.setNameName("sales_08"); //将抛出异常：“工作表已包含此名称（不区分大小写）”)

Parameters:

name - named range name to set (name - 要设置的命名范围名称)

Throws:

java.lang.IllegalArgumentException - if the name is invalid or the already exists within its scope (case-insensitive) (java.lang.IllegalArgumentException - 如果名称无效或在其范围内已经存在（不区分大小写）)

getRefersToFormula

java.lang.String getRefersToFormula()

Returns the formula that the name is defined to refer to. (返回定义名称以引用的公式。)

Returns:

the reference for this name, null if it has not been set yet. Never empty string (此名称的引用，如果尚未设置，则为 null。从不为空字符串)

See Also:

setRefersToFormula(String)

setRefersToFormula

void setRefersToFormula(java.lang.String formulaText)

Sets the formula that the name is defined to refer to. The following are representative examples:

• 'My Sheet'!$A$3
• 8.3
• HR!$A$1:$Z$345
• SUM(Sheet1!A1,Sheet2!B2)
• -PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)

Note: Using relative values like 'A1:B1' can lead to unexpected moving of the cell that the name points to when working with the workbook in Microsoft Excel, usually using absolute references like '$A$1:$B$1' avoids this, see also https://superuser.com/a/1031047/126954 (设置定义名称以引用的公式。以下是代表性示例： 'My Sheet'!$A$3 8.3 HR!$A$1:$Z$345 SUM(Sheet1!A1,Sheet2!B2) -PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount) 注意：使用相对值像 'A1:B1' 可能会导致在 Microsoft Excel 中使用工作簿时名称所指向的单元格发生意外移动，通常使用像 '$A$1:$B$1' 这样的绝对引用可以避免这种情况，另请参见 https:/ /superuser.com/a/1031047/126954)

Parameters:

formulaText - the reference for this name

Throws:

java.lang.IllegalArgumentException - if the specified formulaText is unparsable

isFunctionName

boolean isFunctionName()

Checks if this name is a function name

Returns:

true if this name is a function name

isDeleted

boolean isDeleted()

Checks if this name points to a cell that no longer exists

Returns:

true if the name refers to a deleted cell, false otherwise

isHidden

boolean isHidden()

Checks if this name is hidden, eg one of the built-in Excel internal names

Returns:

true if the name is a hidden name, false otherwise

setSheetIndex

void setSheetIndex(int sheetId)

Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook.

Parameters:

sheetId - the sheet index this name applies to, -1 unsets this property making the name workbook-global

Throws:

java.lang.IllegalArgumentException - if the sheet index is invalid.

getSheetIndex

int getSheetIndex()

Returns the sheet index this name applies to.

Returns:

the sheet index this name applies to, -1 if this name applies to the entire workbook

getComment

java.lang.String getComment()

Returns the comment the user provided when the name was created.

Returns:

the user comment for this named range

setComment

void setComment(java.lang.String comment)

Sets the comment the user provided when the name was created.

Parameters:

comment - the user comment for this named range

setFunction

void setFunction(boolean value)

Indicates that the defined name refers to a user-defined function. This attribute is used when there is an add-in or other code project associated with the file.

Parameters:

value - true indicates the name refers to a function.