Skip to content

Commit 5804492

Browse files
author
yunshi
committed
docs.dev: hyperlink feature analysis
1 parent 17dce95 commit 5804492

File tree

2 files changed

+214
-0
lines changed

2 files changed

+214
-0
lines changed

‎docs/dev/analysis/features/text/hyperlink.rst

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
2+
Hyperlink
3+
=========
4+
5+
Word allows hyperlinks to be placed in the document.
6+
7+
Hyperlink may link to a external location, for example, as an url. It may link to
8+
a location within the document, for example, as a bookmark. These two cases are
9+
handled differently.
10+
11+
Hyperlinks can contain multiple runs of text.
12+
13+
Candidate protocol
14+
------------------
15+
16+
The hyperlink feature supports only external links today (03/2016).
17+
18+
Add a simple hyperlink with text and url:
19+
20+
>>> hyperlink = paragraph.add_hyperlink(text='Google', address='https://google.com')
21+
>>> hyperlink
22+
<docx.text.hyperlink.Hyperlink at 0x7f...>
23+
>>> hyperlink.text
24+
'Google'
25+
>>> hyperlink.address
26+
'https://google.com'
27+
>>> hyperlink.runs
28+
[<docx.text.run.Run at 0x7f...>]
29+
30+
Add multiple runs to a hyperlink:
31+
32+
>>> hyperlink = paragraph.add_hyperlink(address='https://github.com')
33+
>>> hyperlink.add_run('A')
34+
>>> hyperlink.add_run('formatted').italic = True
35+
>>> hyperlink.add_run('link').bold = True
36+
>>> hyperlink.runs
37+
[<docx.text.run.Run at 0x7f...>,
38+
<docx.text.run.Run at 0x7fb...>,
39+
<docx.text.run.Run at 0x7fb...>]
40+
41+
Retrieve a paragraph's content:
42+
43+
>>> paragraph = document.add_paragraph('A plain paragraph having some ')
44+
>>> paragraph.add_run('link such as ')
45+
>>> paragraph.add_hyperlink(address='http://github.com', text='github')
46+
>>> paragraph.iter_run_level_items():
47+
[<docx.text.paragraph.Run at 0x7f...>,
48+
<docx.text.paragraph.Hyperlink at 0x7f...>]
49+
50+
51+
52+
Specimen XML
53+
------------
54+
55+
.. highlight:: xml
56+
57+
58+
External links
59+
~~~~~~~~~~~~~~
60+
61+
An external link is specified by the attribute r:id. The location of the link
62+
is defined in the relationships part of the document.
63+
64+
A simple hyperlink to an external url::
65+
66+
<w:p>
67+
<w:r>
68+
<w:t xml:space="preserve">This is an external link to </w:t>
69+
</w:r>
70+
<w:hyperlink r:id="rId4">
71+
<w:r>
72+
<w:rPr>
73+
<w:rStyle w:val="Hyperlink"/>
74+
</w:rPr>
75+
<w:t>Google</w:t>
76+
</w:r>
77+
</w:hyperlink>
78+
</w:p>
79+
80+
81+
The r:id="rId4" references the following relationship within the relationships
82+
part for the document document.xml.rels.::
83+
84+
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
85+
<Relationship Id="rId4" Mode="External"
86+
Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
87+
Target="http://google.com/"/>
88+
</Relationships>
89+
90+
A hyperlink with multiple runs of text::
91+
92+
<w:p>
93+
<w:hyperlink r:id="rId2">
94+
<w:r>
95+
<w:rPr>
96+
<w:rStyle w:val="Hyperlink"/>
97+
</w:rPr>
98+
<w:t>A</w:t>
99+
</w:r>
100+
<w:r>
101+
<w:rPr>
102+
<w:rStyle w:val="Hyperlink"/>
103+
<w:i/>
104+
</w:rPr>
105+
<w:t xml:space="preserve"> formatted</w:t>
106+
</w:r>
107+
<w:r>
108+
<w:rPr>
109+
<w:rStyle w:val="Hyperlink"/>
110+
<w:b/>
111+
</w:rPr>
112+
<w:t xml:space="preserve"> link</w:t>
113+
</w:r>
114+
</w:hyperlink>
115+
</w:p>
116+
117+
118+
Internal links
119+
~~~~~~~~~~~~~~
120+
121+
An internal link, that link to a location in the document, do not have the r:id attribute
122+
and is specified by the anchor attribute.
123+
The value of the anchor attribute is the name of a bookmark in the document.
124+
125+
Example::
126+
127+
<w:p>
128+
<w:r>
129+
<w:t xml:space="preserve">This is an </w:t>
130+
</w:r>
131+
<w:hyperlink w:anchor="myAnchor">
132+
<w:r>
133+
<w:rPr>
134+
<w:rStyle w:val="Hyperlink"/>
135+
</w:rPr>
136+
<w:t>internal link</w:t>
137+
</w:r>
138+
</w:hyperlink>
139+
</w:p>
140+
141+
...
142+
143+
<w:p>
144+
<w:r>
145+
<w:t xml:space="preserve">This is text with a </w:t>
146+
</w:r>
147+
<w:bookmarkStart w:id="0" w:name="myAnchor"/>
148+
<w:r>
149+
<w:t>bookmark</w:t>
150+
</w:r>
151+
<w:bookmarkEnd w:id="0"/>
152+
</w:p>
153+
154+
155+
Schema excerpt
156+
--------------
157+
158+
.. highlight:: xml
159+
160+
::
161+
162+
<xsd:complexType name="CT_P">
163+
<xsd:sequence>
164+
<xsd:element name="pPr" type="CT_PPr" minOccurs="0"/>
165+
<xsd:group ref="EG_PContent" minOccurs="0" maxOccurs="unbounded"/>
166+
</xsd:sequence>
167+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
168+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
169+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
170+
<xsd:attribute name="rsidP" type="ST_LongHexNumber"/>
171+
<xsd:attribute name="rsidRDefault" type="ST_LongHexNumber"/>
172+
</xsd:complexType>
173+
174+
<xsd:complexType name="CT_Hyperlink">
175+
<xsd:group ref="EG_PContent" minOccurs="0" maxOccurs="unbounded"/>
176+
<xsd:attribute name="tgtFrame" type="s:ST_String" use="optional"/>
177+
<xsd:attribute name="tooltip" type="s:ST_String" use="optional"/>
178+
<xsd:attribute name="docLocation" type="s:ST_String" use="optional"/>
179+
<xsd:attribute name="history" type="s:ST_OnOff" use="optional"/>
180+
<xsd:attribute name="anchor" type="s:ST_String" use="optional"/>
181+
<xsd:attribute ref="r:id"/>
182+
</xsd:complexType>
183+
184+
<xsd:group name="EG_PContent"> <!-- denormalized -->
185+
<xsd:choice>
186+
<xsd:element name="r" type="CT_R"/>
187+
<xsd:element name="hyperlink" type="CT_Hyperlink"/>
188+
<xsd:element name="fldSimple" type="CT_SimpleField"/>
189+
<xsd:element name="sdt" type="CT_SdtRun"/>
190+
<xsd:element name="customXml" type="CT_CustomXmlRun"/>
191+
<xsd:element name="smartTag" type="CT_SmartTagRun"/>
192+
<xsd:element name="dir" type="CT_DirContentRun"/>
193+
<xsd:element name="bdo" type="CT_BdoContentRun"/>
194+
<xsd:element name="subDoc" type="CT_Rel"/>
195+
<xsd:group ref="EG_RunLevelElts"/>
196+
</xsd:choice>
197+
</xsd:group>
198+
199+
<xsd:complexType name="CT_R">
200+
<xsd:sequence>
201+
<xsd:group ref="EG_RPr" minOccurs="0"/>
202+
<xsd:group ref="EG_RunInnerContent" minOccurs="0" maxOccurs="unbounded"/>
203+
</xsd:sequence>
204+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
205+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
206+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
207+
</xsd:complexType>
208+
209+
<xsd:simpleType name="ST_RelationshipId">
210+
<xsd:restriction base="xsd:string"/>
211+
</xsd:simpleType>
212+

‎docs/dev/analysis/features/text/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,5 @@ Text
1212
underline
1313
run-content
1414
breaks
15+
hyperlink
16+

0 commit comments

Comments
 (0)